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 mesh
> 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
;)
> We can't just say "Your comments will be interpreted by the
> doc tool for the target language" because that makes it very hard to write
> 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.
> So for Javadoc we'd presumably
> need to wrap the whole comment in <pre></pre>. I'm not sure how that would
> 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.
>> > Just take whatever comments appear before / on the same line as the
>> > field,
>> > as you describe.
>> > One tricky issue is formatting. Javadoc requires paragraphs to be
>> > explicitly delimited using HTML (<p>). I've always found this really
>> > 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:
>> > // Blah blah blah here is a list:
>> > // * blah blah blah
>> > // * blah blah blah blah
>> > // * 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:
>> > // Blah blah blah, here is some example code:
>> > // foo(bar);
>> > // baz.qux();
>>
>> > Not to be confused with comments like this:
>> > // TODO(kenton): Blah blah blah blah. Note that
>> > // for TODOs I indent lines after the first. I'm not
>> > // 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 than
>> > 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
>> /*
>> * Foo
>> *
>> * Bar
>> */
>> Leading and trailing newlines are eaten; this is equivalent to
>> // Foo
>> //
>> // Bar
>>
>> Both would result in " Foo\n\n Bar" (maybe with the removal of the
>> leading space).
>>
>> To accommodate other comment styles, superfluous leading comment
>> characters are removed as well
>> //// Foo
>> //// Bar
>> or
>> /** Foo
>> *** Bar
>> ***/
>> will both result in " Foo\n Bar".
>>
>>
>> > Maybe you could do a survey of
>> > some existing .proto files to try to figure out the common patterns, and
>> > 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 my
>> >> 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 the
>> >> 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
>> >> * comment
>> >> */
>> >> message Foo {
>> >>
>> >> /* some stray comment, not part of a field documentation */
>> >>
>> >> /*
>> >> * some block comment
>> >> */
>> >> int32 some_field = 1;
>> >>
>> >> int32 some_other_field = 2; // short comment.
>> >>
>> >> // Some stray comment, not part of a field. No documentation.
>> >>
>> >> // Some block comment
>> >> // comprising of consecutive //-style comments
>> >> // over multiple lines with no newline in-between
>> >> int32 yet_another_field = 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 need
>> >> ? 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 line
>> >> 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 proto...@googlegroups.com.
>> >> To unsubscribe from this group, send email to
>> >> protobuf+unsubscr...@googlegroups.com.
>> >> For more options, visit this group at
>> >> http://groups.google.com/group/protobuf?hl=en.
>> >>
>> >>
>> >
>> >
>
>
--
You received this message because you are subscribed to the Google Groups
"Protocol Buffers" group.
To post to this group, send email to proto...@googlegroups.com.
To unsubscribe from this group, send email to
protobuf+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/protobuf?hl=en.
