Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lisroach/Protoxygen

Use Doxygen to document Protobuf files
https://github.com/lisroach/Protoxygen

Last synced: 3 months ago
JSON representation

Use Doxygen to document Protobuf files

Awesome Lists containing this project

README 

        
# Protoxygen

### Use Doxygen to document Protobuf files



#### Purpose



This project is designed to allow users to document [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) using [Doxygen](http://www.stack.nl/~dimitri/doxygen/). 



#### File Breakdown



The proto2cpp.py file is a filter created by Timo Marjoniemi that is located on [SourceForge](https://sourceforge.net/projects/proto2cpp/). 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](http://stackoverflow.com/questions/36609243/input-filter-in-doxygen-adding-to-mainpage) 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.