generating proto documentation

[bart van deenen]

Hi all

How do you document .proto files? I'd love to really define our
protocol with javadoc/qtdoc/doxygen tags inside the .proto files, and
generate html documentation from that.

Does anyone already have a solution, or something in the works that we
can improve on?

[Mark Assad]

HI, 

  I have a bad solution. What I've been doing has been generating the .cc/.h files, and then using doxygen to document those classes. You can document C++ classes from files other than the header files that define the classes.  It's messy, error prone, and you end up with a lot of extra methods document that you really don't want. In summary, I'd suggest doing it another way.  The detailed message documentation is lost in a sea of undocumented methods.  

  In the past, I have started working on patching doxygen to read and parse .proto files. I didn't get as far as I would have liked. I also looked at using the compiler/parser that is part of the protobuf source code, but that strips out the comments.  My other thought was to use a custom option for the comment string. Then writer a Python script that read in the descriptor proto file, and generated documentation from that.  The other thought I had was to patch the C++ code generator class to generate comments in the source files in the doxygen format, but I didn't want to tie the code generator to a documentation format. 

 I still think the best option would be to update doxygen to support reading the .proto files, but it is also the most work (maybe not in the long term). 

Mark

[bart van deenen]

I'm thinking of writing some scripting stuff, convert 'message' to
'struct' and stuff like that, and see how far I'll get with converting
proto files into some sort of pseudo-c. I think I'll mogrify the
'optional' and 'required' and 'repeated' flags to some custom doxygen
tags. As soon as I have something, I'll put it on github as an
opensource project.

On Mar 17, 10:49 am, Mark Assad <mas...@gmail.com> wrote:
> HI,
>   I have a bad solution. What I've been doing has been generating the .cc/.h
> files, and then using doxygen to document those classes. You can document
> C++ classes from files other than the header files that define the classes.
>  It's messy, error prone, and you end up with a lot of extra methods
> document that you really don't want. In summary, I'd suggest doing it
> another way.  The detailed message documentation is lost in a sea of
> undocumented methods.
>
>   In the past, I have started working on patching doxygen to read and parse
> .proto files. I didn't get as far as I would have liked. I also looked at
> using the compiler/parser that is part of the protobuf source code, but that
> strips out the comments.  My other thought was to use a custom option for
> the comment string. Then writer a Python script that read in the descriptor
> proto file, and generated documentation from that.  The other thought I had
> was to patch the C++ code generator class to generate comments in the source
> files in the doxygen format, but I didn't want to tie the code generator to
> a documentation format.
>
>  I still think the best option would be to update doxygen to support reading
> the .proto files, but it is also the most work (maybe not in the long
> term).
>
> Mark
>
> On Tue, Mar 17, 2009 at 8:28 PM, bart van deenen

> <bart.vandee...@gmail.com>wrote:

[bart van deenen]

Hi all

I've set up an initial repos here : http://github.com/bvdeenen/proto2c/tree/master
It's one python script that you can run with one .proto file as a
command line argument. It generates valid c (except for messages with
nested enum definitions), which you can process with doxygen.

Its just a first step, but it already works fairly well.

The bugs are numerous:
* it is very line based; it expects one enum value on 1 line for
instance.
* I've never used groups, or extensions or stuff like that, its not in
it.

I'll continue working on it, and will regularly update the repos. If
you want to help out, don't hesitate to get in touch with me.


Bart

On Mar 17, 10:49 am, Mark Assad <mas...@gmail.com> wrote:

> HI,
>   I have a bad solution. What I've been doing has been generating the .cc/.h
> files, and then using doxygen to document those classes. You can document
> C++ classes from files other than the header files that define the classes.
>  It's messy, error prone, and you end up with a lot of extra methods
> document that you really don't want. In summary, I'd suggest doing it
> another way.  The detailed message documentation is lost in a sea of
> undocumented methods.
>
>   In the past, I have started working on patching doxygen to read and parse
> .proto files. I didn't get as far as I would have liked. I also looked at
> using the compiler/parser that is part of the protobuf source code, but that
> strips out the comments.  My other thought was to use a custom option for
> the comment string. Then writer a Python script that read in the descriptor
> proto file, and generated documentation from that.  The other thought I had
> was to patch the C++ code generator class to generate comments in the source
> files in the doxygen format, but I didn't want to tie the code generator to
> a documentation format.
>
>  I still think the best option would be to update doxygen to support reading
> the .proto files, but it is also the most work (maybe not in the long
> term).
>
> Mark
>
> On Tue, Mar 17, 2009 at 8:28 PM, bart van deenen

> <bart.vandee...@gmail.com>wrote:

[bart van deenen]

Hi all

I'm answering myself here.

I have a useful first step solution; a Python script that mogrifies
the proto files into a pile of C structs that can be handled by
doxygen. The python stuff is at

http://github.com/bvdeenen/proto2c/tree/master

an can be used
proto2c.py <protofile> > <c-file>

Then process the c file with doxygen to generate html.

It works pretty well for the large protocol file I'm using, but there
are quite a bit of legal protocol documents that it will choke on.
I'll be working on it the coming week, and at least have the following
plans:

* handle import statements
* handle enums on one line


Bart

[OJW]

I've put up the perl script we use to generate documentation of proto
files:

http://dev.openstreetmap.org/~ojw/proto2wikidoc

Our proto files are in quite a simplified format, so this probably
won't parse your files without modification. However, it's a base to
start from if anyone wants to add better parsing etc.

sample output at:

http://dev.openstreetmap.org/~ojw/proto2wikidoc/index.php/Myprotocol_protocol

thanks to cueSim for releasing the code. Thanks to openstreetmap for
(unknown to them) hosting the project page.