documentation within proto files

[Romain François]

Hi,

What is the recommended way to include some documentation within the
proto file ?

Something like this perhaps.

/**
* a person
*/
message Person {
/** identifier */
required int32 id = 1;

/** Name of the person. first name and last name */
required string name = 2;

/** email address */
optional string email = 3;
}

I realize there are no API to grab these from the FooDescriptor objects,
but maybe something is planned ?

Romain

--
Romain Francois
Professional R Enthusiast
+33(0) 6 28 91 30 30
http://romainfrancois.blog.free.fr
|- http://tr.im/BcPw : celebrating R commit #50000
|- http://tr.im/ztCu : RGG #158:161: examples of package IDPmisc
`- http://tr.im/yw8E : New R package : sos

[Kenton Varda]

There's no convention for this currently.  If you want to see how Google documents things, look at descriptor.proto:

http://protobuf.googlecode.com/svn/trunk/src/google/protobuf/descriptor.proto

But it's not very exciting.

2009/11/2 Romain François <francoi...@free.fr>

[Evan Jones]

On Nov 2, 2009, at 12:14 , Kenton Varda wrote:
> There's no convention for this currently.

It would be pretty nice to have the parser parse some form of doc
comments. Then the language backends could output them appropriately:
javadoc for Java, docstrings for Python, etc. Not that I'm
volunteering to do the work though. :)

Evan

--
Evan Jones
http://evanjones.ca/

[Kenton Varda]

We all agree it would be nice, but no one has volunteered to do it.  :)

There's also the question of where, exactly, you put the comments given that each field expands to several methods.  Does each method get a copy of the same comments?  Or do they all refer to a common copy?