Re: Javadoc Comment Formatting
Eric Blake <[EMAIL PROTECTED]> writes: > I agree with the sentiment that the final output is worth the reduced > readability in the source code, but I am willing to go with the majority > on this decision, whichever way it gets decided. The tool will probably dictate the matter. Brian -- Brian Jones <[EMAIL PROTECTED]> ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
Re: Javadoc Comment Formatting
I am not opposed to doing better markup of comments in my code. As I write doc comments, I have been trying to make formatted lists correctly, use < instead of <, and other things; but I do not always get it correct. Further, I have not tested my documentation work by running it through any tool, free or from Sun, so I'm sure I have contributed buggy comments. When I code, I prefer to consult well-formatted HTML, XML, or texinfo comments than trying to read comments inline. One reason is that a well-done markup version has hyperlinks that inline code does not, and as nice as etags is for emacs, it's not perfect. I agree with the sentiment that the final output is worth the reduced readability in the source code, but I am willing to go with the majority on this decision, whichever way it gets decided. Julian Scheid wrote: > > I find this issue not paramount but in order to offer > high-quality documentation in various formats, I think we should > propose some guidelines for contributors, including the advice to > structure comments using (correct) HTML tags where necessary. > Reduces inline readability but enhances output readability, > integrity, portability and transformability. Wow!! ;) > > Other opinions are very welcome. > -- This signature intentionally left boring. Eric Blake [EMAIL PROTECTED] BYU student, free software programmer ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
Re: Javadoc Comment Formatting
Nic Ferrier wrote: > But none of that is really important. The bottom line is: you will > never get all the authors of source code to write well-formed XHTML, > you're always going to miss something. That's why it sucks. OK if this is the problem, let me put it that way: If we _aim_ towards having 100% well-formed XHTML comments, by asking developers to close their open tags etc., the XML doclet would have less trouble outputting valid XML code, which in turn would lead to a higher-quality HTML documentation (and other documentation generated via XSLT.) Besides, as I mentioned before it would be quiet easy to write a doclet which checks every comment for well-formedness. Actually, XML doclet is already quiet tolerant and with a few added out.printlns could provide you with information like e.g. this: WARNING: in java.lang.Number.compareTo(Object) comment (near line 123): (comment line 5) '<' taken as literal - tag looks like email address. WARNING: in java.lang.String class comment (near line 42): (comment line 7) Unclosed tag (comment line 8) Unclosed tag So "missing something" would only be possible when ignoring these warnings. WRT the readability issue: actually, a good deal of Classpath javadoc comments completely lack any HTML tags and are only formatted using indentation and line breaks. While this is of course very legible when looking at the code, and may produce good-looking (though non-standard) Info output, the XML/XSLT solution will not be able to produce good-looking HTML code from this (or any structured output other than plain text-based formats). I find this issue not paramount but in order to offer high-quality documentation in various formats, I think we should propose some guidelines for contributors, including the advice to structure comments using (correct) HTML tags where necessary. Reduces inline readability but enhances output readability, integrity, portability and transformability. Wow!! ;) Other opinions are very welcome. ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
Re: Javadoc Comment Formatting
Julian Scheid <[EMAIL PROTECTED]> writes: > I'll leave that for discussion. My opinion is: make > comments XHTML compliant and ease the task for > writers/maintainers by supplying appropriate (XHTML > checking, and perhaps fixing) tools. Live with degraded > readability, or better: view the documentation generated > by Texinfo doclet instead of consulting inline comments. > > (Most of the time, you will be looking up docs for a > method different from that you are currently working on, > so in terms of keystrokes it isn't a big difference > whether you open another file and browse to the method > definition, or you open the info docs for that method > - provided you are using something like jtxd.el for > quick access to generated documentation.) It depends on what you're doing. If you're the maintainer of some source code then you're right, whilst you're hacking it you are probably looking up methods in other places (having said that all the useful browser tools we have so far deal with source code files, not a documentation tree). But that isn't the only audience for source code, it's not even the main audience (for most GNU code). Most GNU code has a very long life and is hacked on by many people. I hate picking up java code where there is XHTML javadoc because it's so hard to read. But none of that is really important. The bottom line is: you will never get all the authors of source code to write well-formed XHTML, you're always going to miss something. That's why it sucks. Nic ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
Re: Javadoc Comment Formatting
Nic Ferrier wrote: > I do agree that XML is the way forward (docbook might make a good > replacement for texinfo when it has widespread support like texinfo) > but the issue of in-source readable comments will need to be solved > before it is a really practical option. It seems to boil down to inline readability and easy comment maintenance on one hand, and full XHTML compliance for enabling arbitrary XSLT conversions on the other. I agree that strictly applying the XHTML standard will degrade readability and add an additional burden for documentation writers/maintainers, but for that you gain 100% XML compliance with all eventual benefits. I'll leave that for discussion. My opinion is: make comments XHTML compliant and ease the task for writers/maintainers by supplying appropriate (XHTML checking, and perhaps fixing) tools. Live with degraded readability, or better: view the documentation generated by Texinfo doclet instead of consulting inline comments. (Most of the time, you will be looking up docs for a method different from that you are currently working on, so in terms of keystrokes it isn't a big difference whether you open another file and browse to the method definition, or you open the info docs for that method - provided you are using something like jtxd.el for quick access to generated documentation.) > Can't you intelligently escape such things? for example if they don't > turn out to be valid xml. As I said, XML doclet already does something like this. It even tries to guess where unclosed tags are ending and inserts appropriate closing tags, to some extent. But this is more of a hack and quiet error prone - after all, it involves a lot of guessing if you have input whose format is not defined umambigiously. Julian ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
Re: Javadoc Comment Formatting
I'm not sure this should be discussed here but...
Julian Scheid <[EMAIL PROTECTED]> writes:
> Now the Classpath comments do sometimes contain stuff like
>
> /**
>* ... maintained by <[EMAIL PROTECTED]>
>* ...
>*/
>
> and
>
> /**
>* ... for example,
>*
>* if (a < b) { ... }
>*
>* ...
>*/
>
> That's no well-formed HTML of course, as the less-than signs
> are normally interpreted as beginning-of-tag. I agree that
>
>* if (a < b) { ... }
>
> isn't as readable as the original shown above (when looking
> at the inline comments), but it's more correct in terms of
> well-formedness. Gjdoc currently goes to some lengths to
> recognize less-than signs that are not beginning-of-tag but
> instead meant to stay as a literal character. But I think
> in the long term, the proper solution is to adapt the comment
> code and not the doclet driver.
Personally I think that's the wrong way round. Javadoc is really
useful as an inline doc system as well as for producing a bunch of
nicely formatted doc pages.
Can't you intelligently escape such things? for example if they don't
turn out to be valid xml. Given the GNU coding standard you very
rarely see thing like this:
*
* if (a From my point of view, comment code would ideally be 100%
> well-formed XHTML: all special characters expressed as XML
> entities, all open tags closed, all tag attribute values in
> quotes, all tags properly nested.
> (For more information, see )
But from the point of view of someone wanting to hack code quickly
the comments should be readable. Well-formed XHTML is not necessarily
readable.
> Perhaps I should also mention that Nic Ferrier has suggested
> (and AFAIK actually started in his Paperclips project) to
> use TexInfo formatting instead of HTML formatting in Javadoc
> comments, arguing that TexInfo is the de-facto GNU
> documentation standard and that TexInfo is better readable
> than HTML when looking at the source code.
>
> My opinion is, while TexInfo may be standard for GNU docs in
> general, HTML is the standard for Javadoc comments. There are
> plenty of tools (partly GPLed) already out there which operate
> on Javadoc comments and expect them to be in HTML format
> (including XML doclet.)
>
> Also, TexInfo is a decent format but thinking of XSLT sheets,
> X(HT)ML is more flexible as it allows generic transformations
> to virtually any target format, while there is no
> corresponding technology for transforming TexInfo code AFAIK.
Except info->SOMETHING drivers are quite easy to write and GNU has
lots of experience at them.
I do agree that XML is the way forward (docbook might make a good
replacement for texinfo when it has widespread support like texinfo)
but the issue of in-source readable comments will need to be solved
before it is a really practical option.
> For these reasons I don't share Nics point of view on this
> issue. I think we (and any other GNU project) should stick
> to using HTML in comments, preferrably well-formed XHTML.
I just don't believe it's reasonable, it's hard enough to get people
to write code to the coding standard, let alone the doc comments.
The problem is that XHTML throws such spanners in the works, the
example you cited before is a really good one, so it this:
/**
* This is a method that writes some stuff.
* The outputstream gets something like this:
*
* this is the concat of a & b
*
which of course won't work. Using the less than sign, the greater
than sign and other HTML reserved words is quite common in javadoc
comments and having to remember the HTML is a great big pain in the
neck.
The equivalent in texinfo, of course, does not cause such problems.
Nic
___
Classpath mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/classpath
