I am certainly not arguing for HTML -- I am arguing against it. Something wiki-like would be cool (usually I hate wiki but in this context I think it makes sense)... but I think that would be too big a dependency for what we're trying to do. So I think just embedding ASCII art with <pre> makes sense.
On Tue, Dec 22, 2009 at 3:27 PM, Henner Zeller <[email protected] > wrote: > On Tue, Dec 22, 2009 at 15:04, Kenton Varda <[email protected]> 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 <[email protected]> wrote: > >> > >> On Tue, Dec 22, 2009 at 14:30, Kenton Varda <[email protected]> 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 > >> > <[email protected]> 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 [email protected]. > >> >> To unsubscribe from this group, send email to > >> >> [email protected]<protobuf%[email protected]> > . > >> >> 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 [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/protobuf?hl=en.
