lisroach / protoxygen

Use Doxygen to document Protobuf files

Protoxygen

Use Doxygen to document Protobuf files

Purpose

This project is designed to allow users to document Google Protocol Buffers using Doxygen.

File Breakdown

The proto2cpp.py file is a filter created by Timo Marjoniemi that is located on SourceForge. I have made some changes to this filter in order to better document the 'Services' portion of protobufs.

The proto2cpp file takes protobuf and translates the code to C++ readable keywords, allowing Doxygen to document the comments. But, we do not want the generated output to look like C++ code, as we will not be able to relate it to the original protobuf files. To solve this, I have written the protofy.sh file, which crawls the generated HTML documents and replaces the C++ keywords with the appropriate protobuf keyword.

DoxygenLayout is an xml file that is generated by Doxygen. I have made changes to page titles and link names in order to, again, replace the C keywords with protobuf keywords.

doc-gen.sh is the script to run to generate the doxygen.

How to Comment

Protobuf files need to be commented a specific way in order for them to be read by Doxygen.

To document Services, I have them grouped based on the name of the service. An example follows:

//@defgroup MyService
// My service brief description!
// My service more detailed description
//@{
service MyService {
	//@addtogroup MyService
	//@{
	//;
	
	// Description of my RPC call
	rpc RPCCall(sent) returns (response);
	
	//@}
}

// This is my message example
message MyMessage {
	// comment
	string my_value = 1;
}

//@}

One of the odd things is the //; on the 8th line. I find that without a semicolon above the first RPC call, Doxygen will not properly document the very first call. In the proto2cpp script the // is removed from in front of the ;. This means you CANNOT USE SEMICOLONS IN YOUR COMMENTS. If you do, the // will be removed from your comment line. This has room for improvement, and I will be working on changing this caveat.

Issues

The above paragraph explains that you cannot use semicolons in your comments, and you need to include a commented semicolon above the first RPC call of every service.

Another issue is something I have mailed the DoxygenUsers group and posted a StackOverflow question about, without any response. The proto2cpp will always add itself to the beginning of my mainpage when I attempt to use a README.md as the mainpage document. This may be a bug in doxygen itself. To get around it, the final line in protofy.sh removes the begining lines of the index.html page to clear out the proto2cpp text. If you are not using a markdown file as your index, you may not run into this issue and will have to remove that line from the protofy.sh.

protoxygen's Issues

No License

Hi 👋
Thanks for the work you have done in this repo.

As stated by the README in this repo, the code originally came from SourceForge where it was released using the GNU Lesser General Public License version 2.1.

I think it makes sense to add a license file to this repo that makes this fact clear.

Problem with oneof

First of all thank you very much for this very good implementation, makes it very clear what are services and what are not.

I just found a issue that oneof parameters are not handled well, could not yet find the error in the pyton script.

message ConversionParameters {
	oneof Parameters
	{
		int32	Quality = 2;
		int32	MaxFileSize = 3;
	}
	optional ImageDpi Dpi = 4;
}