commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simon Kitching <skitch...@apache.org>
Subject Re: Javadoc formatting style
Date Mon, 07 Feb 2005 03:31:39 GMT
On Sun, 2005-02-06 at 18:59 -0800, Craig McClanahan wrote:
> On Sun, 6 Feb 2005 21:45:08 -0500, Henri Yandell <flamefew@gmail.com> wrote:
> > My reason is quite a lot simpler than Craig's.
> > 
> > I think of <p> as a container tag and not a separator tag, so I never
> > even think of the other way of doing it.
> > 
> > I guess we could do:
> > 
> > /**
> >  * first
> >  * <p/>
> >  * second
> >  */
> > 
> > and still be XML compliant (assuming an automatic root of some kind),
> > but it would seem just as wrong to me.
> 
> It would be valid only if the element that the Javadoc doclet happens
> to place around your Javadoc comments accepts mixed content, *AND* if
> the nested content is itself well formed.  Java developers who count
> on that are, IMHO, making a mistake.

I was under the impression that "doclet" plugins to javadoc are always
fed properly structured data, in the same way that the Necko
html-parsing library presents its input data to its users as if it were
well-formed xml, and therefore don't need to worry about whether the
original javadoc text was HTML or XHTML style.

Is this not the case? If doclets are exposed to the raw javadoc text
then I would definitely agree XHTML is the way to go...

> Of course, I feel the same way about developers creating static HTML
> pages that create non-well-formed markup :-).

For HTML I agree; XHTML is the way to go. But isn't javadoc is a bit
different? In particular, it is read much more frequently in its raw
form, and always written by hand. And it is also expected to be accessed
via the javadoc "doclet" api rather than read directly(?).

Regards,

Simon


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message