Thinking of implementing: extract documentation in .proto file and store in FileDescriptorProto - Protocol Buffers

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion Thinking of implementing: extract documentation in .proto file and store in FileDescriptorProto
Received-SPF: pass (google.com: domain of henner.zel...@googlemail.com designates 209.85.216.179 as permitted sender) client-ip=209.85.216.179;
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=googlemail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :cc:content-type:content-transfer-encoding;
        b=fkMjOvN7E2fgCdj1IcAuwKyq48UD83vJnaipUXpR7+tAn0xpZa7M8U5SKxJsEeLmQr
         eFvoAoNH35hWeXDK8Th2BQnDqIx1W/ew7i/C+V8dXcjPeoEQj1yn4XM1eyMKX2gXT+p6
         rmzI0aOuykvRcNYCg6u+t6jkkdTgbNiIq0L1E=
MIME-Version: 1.0
In-Reply-To: <4112ecad0912221504p4049501at17628e5c447f5...@mail.gmail.com>
References: <952789670912221353g1376fb58xb865be02c13be...@mail.gmail.com>
	 <4112ecad0912221430y5eb6fb6co20d108b21b03...@mail.gmail.com>
	 <952789670912221456i2f05334bkef5de3f4b8e80...@mail.gmail.com>
	 <4112ecad0912221504p4049501at17628e5c447f5...@mail.gmail.com>
Date: Tue, 22 Dec 2009 15:27:30 -0800
Message-ID: <952789670912221527i745871c3xf1fda415e1141...@mail.gmail.com>
Subject: Re: [protobuf] Thinking of implementing: extract documentation in 
	.proto file and store in FileDescriptorProto
From: Henner Zeller <henner.zel...@googlemail.com>
To: Kenton Varda <ken...@google.com>
Cc: Protocol Buffers <protobuf@googlegroups.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On Tue, Dec 22, 2009 at 15:04, Kenton Varda <ken...@google.com> wrote:
> Preserving ASCII art sounds great to me, but I'm not sure how this will m=
esh
> with Javadoc.

If we just pass through HTML formatting for folks that mainly work
with Java, that would be fine. But I don't want my C++ code (and for
that matter, my .proto-files) cluttered with HTML formatting gibberish
;)

> =A0We can't just say "Your comments will be interpreted by the
> doc tool for the target language" because that makes it very hard to writ=
e
> comments that work nicely in all languages.

So instead of HTML, maybe some simple wiki like syntax ? But I guess
that would be overthinking the problem right now. Problem is, that it
is even worse parsing arbitrary HTML documentation if you want convert
it to a documentation format that does not support HTML.

> =A0So for Javadoc we'd presumably
> need to wrap the whole comment in <pre></pre>. =A0I'm not sure how that w=
ould
> end up looking.

Going with <pre></pre>, maybe with the heuristics if there are no
HTML-formattings found in the comment, sounds like a good initial
solution to me.

-h

> On Tue, Dec 22, 2009 at 2:56 PM, Henner Zeller <h.zel...@acm.org> wrote:
>>
>> On Tue, Dec 22, 2009 at 14:30, Kenton Varda <ken...@google.com> wrote:
>> > I agree, I don't think we should require a specific style for doc
>> > comments.
>> > =A0Just take whatever comments appear before / on the same line as the
>> > field,
>> > as you describe.
>> > One tricky issue is formatting. =A0Javadoc requires paragraphs to be
>> > explicitly delimited using HTML (<p>). =A0I've always found this reall=
y
>> > annoying -- why can't it automatically insert paragraph breaks when it
>> > sees
>> > blank lines?
>>
>> I would not go with any paragraph formatting as suggested by JavaDoc,
>> just do a plain conversion of the comment, complete with newlines, but
>> with comment characters removed. So the final comment would actually
>> contain newlines so would need to be re-encoded with comment
>> characters in the particular target language if needed. If there is a
>> tool that generates HTML out of it, it has to include <br/> or <p> as
>> it pleases.
>>
>> So the following comment:
>> > But more difficult is comments like this:
>> > =A0=A0// Blah blah blah here is a list:
>> > =A0=A0// * blah blah blah
>> > =A0=A0// * blah blah blah blah
>> > =A0=A0// * blah blah
>>
>> Would become " Blah blah blah here is a list:\n * blah blah blah ..."
>> Note that would remove the comment characters but leave the
>> whitespaces in front of the comments intact. Maybe we could remove the
>> common prefix whitespaces (so minimum of whitespaces found on all
>> lines of a block).
>>
>> > Or comments like this:
>> > =A0=A0// Blah blah blah, here is some example code:
>> > =A0=A0// =A0 foo(bar);
>> > =A0=A0// =A0 baz.qux();
>>
>> > Not to be confused with comments like this:
>> > =A0=A0// TODO(kenton): =A0Blah blah blah blah. =A0Note that
>> > =A0=A0// =A0 for TODOs I indent lines after the first. =A0I'm not
>> > =A0=A0// =A0 exactly sure why I do this but I always have.
>>
>> Garbage in, garbage out ;) So you would get a multi-line comment with
>> a different number of whitespaces in front of each line (maybe with
>> the common number of whitespaces (i.e. one) removed from all of them,
>> as suggested above).
>>
>> > Ideally I'd like to come up with reasonable rules which allow us to
>> > infer
>> > the proper formatting for comments that already exist today, rather th=
an
>> > require developers to add explicit markup.
>>
>> I am purely for ASCII art formatting here - this is what the developer
>> writes in the proto file and this it what will end up in generated
>> source file - so exactly what everyone would expect. If people want to
>> add additional formatting to make stuff look good in HTML formatting,
>> then they'll get it, but I don't think the protocol compiler should do
>> anything with it except passing through.
>>
>> So in particular, a newline is added by having an empty line in a block
>> comment
>> =A0/*
>> =A0 * Foo
>> =A0 *
>> =A0 * Bar
>> =A0 */
>> Leading and trailing newlines are eaten; this is equivalent to
>> =A0// Foo
>> =A0//
>> =A0// Bar
>>
>> Both would result in " Foo\n\n Bar" =A0(maybe with the removal of the
>> leading space).
>>
>> To accommodate other comment styles, superfluous leading comment
>> characters are removed as well
>> =A0//// Foo
>> =A0//// Bar
>> or
>> =A0 /** Foo
>> =A0 *** Bar
>> =A0 ***/
>> will both result in " Foo\n Bar".
>>
>>
>> > =A0Maybe you could do a survey of
>> > some existing .proto files to try to figure out the common patterns, a=
nd
>> > then detect those?
>>
>> Yeah, I've seen already in descriptor.proto, that you sometimes have
>> multi-line post-enum-value comments ( "Not ZigZag encoded. ..."). In
>> my little survey of some other protocol buffers, I've seen this style
>> sometimes, but I think that is too fragile to support as general
>> documentation style. So these have to changed to pre-enum-value block
>> comments.
>>
>> I think after the basic implementation we can easily write a JavaDoc
>> like HTML documentation tool; in the generated doc we then will see
>> comments that are off and see if things need tweaking.
>>
>> -h
>>
>> > On Tue, Dec 22, 2009 at 1:53 PM, Henner Zeller
>> > <henner.zel...@googlemail.com> wrote:
>> >>
>> >> Hi,
>> >> Since this question came up earlier today and I have this anyway on m=
y
>> >> TODO list, I think this is as well some nice side project for the
>> >> holidays I could work on ;)
>> >>
>> >> Basically, there are two forms of comments typically found for
>> >> messages and fields: block comments in front of the declaration of th=
e
>> >> message/field and a single end-of-line comment at the end of a field.
>> >> While often block comments are regarded as a multi-line /* ... */
>> >> block, I'd as well like to see a multi-line comment as multiple
>> >> consecutive lines of //-style comments:
>> >>
>> >> /* some block
>> >> =A0* comment
>> >> =A0*/
>> >> message Foo {
>> >>
>> >> =A0/* some stray comment, not part of a field documentation */
>> >>
>> >> =A0/*
>> >> =A0 * some block comment
>> >> =A0 */
>> >> =A0int32 some_field =3D 1;
>> >>
>> >> =A0int32 some_other_field =3D 2; =A0// short comment.
>> >>
>> >> =A0// Some stray comment, not part of a field. No documentation.
>> >>
>> >> =A0// Some block comment
>> >> =A0// comprising of consecutive //-style comments
>> >> =A0// over multiple lines with no newline in-between
>> >> =A0int32 yet_another_field =3D 3;
>> >> }
>> >>
>> >> There are several documentation styles out there such as JavaDoc or
>> >> Doxygen that require a particular start of a comment (like /** .. */
>> >> or /*! .. */ or ///... ). Is this a constraint we want to have or nee=
d
>> >> ? I think this makes sense for these documentation tools as they are
>> >> designed for code that can have some arbitrary comments in-between.
>> >> The only requirement I'd propose is that there should be no empty lin=
e
>> >> between a block comment and the field/message it describes. This
>> >> enforces readability and prevents stray comments or file-header
>> >> comments being accidentally included in the documentation.
>> >>
>> >> Thoughts ?
>> >>
>> >> H.
>> >>
>> >> --
>> >>
>> >> You received this message because you are subscribed to the Google
>> >> Groups
>> >> "Protocol Buffers" group.
>> >> To post to this group, send email to protobuf@googlegroups.com.
>> >> To unsubscribe from this group, send email to
>> >> protobuf+unsubscribe@googlegroups.com.
>> >> For more options, visit this group at
>> >> http://groups.google.com/group/protobuf?hl=3Den.
>> >>
>> >>
>> >
>> >
>
>
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
