Preserving ASCII art sounds great to me, but I'm not sure how this will mesh
with Javadoc. 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 for Javadoc we'd presumably
need to wrap the whole comment in <pre></pre>. I'm not sure how that would
end up looking.
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<protobuf%2bunsubscr...@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.
