commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Henri Yandell <flame...@gmail.com>
Subject Re: Javadoc formatting style
Date Mon, 07 Feb 2005 02:45:08 GMT
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.

Hen

On Sun, 6 Feb 2005 18:22:42 -0800, Craig McClanahan <craigmcc@gmail.com> wrote:
> The standard HTML format is *not* the only output format you can get
> with Javadocs -- it is quite feasible to render alternative XML-based
> formats that can then be transformed using standard XML technologies
> -- but that only works if the markup created by Javadocs comments is
> well formed.
> 
> In addition, the lack of rigor that HTML requires has always been my
> least favorite thing about the web in general -- I wish we'd started
> with a culture that requires well formed XML in the first place.  Not
> having done so has had a *direct* impact on the portability of
> documents across browsers, and that impact has been negative overall.
> 
> The same mistake has essentially been made with RSS -- instead of
> being disciplined about what they produce, RSS providers have expected
> the newsfeed readers to go through incredible contortions to read
> invalid feeds.  That philosophy is backwards.
> 
> I prefer to set a good example on things like this, rather than
> contributing to the problem.
> 
> Craig
> 
> 
> On Mon, 07 Feb 2005 15:06:49 +1300, Simon Kitching <skitching@apache.org> wrote:
> > On Sun, 2005-02-06 at 17:18 -0800, Craig McClanahan wrote:
> > > As should be evident from my own recent practice :-), I'm also +1 on
> > > the first (XHTML) approach.
> >
> > Can I ask those supporters of the XHTML style why they prefer it?
> >
> > Personally I think it:
> > * increases the text size of the source file
> > * is harder to write manually (and harder to write correctly)
> > * makes the docs in the source file harder to read
> > * might be easier for the javadoc app to parse, but that
> >   makes no difference to us users of javadoc; the javadoc
> >   tool support for HTML-style isn't going away.
> > and
> > * has no effect whatsoever on the generated html pages
> >
> > Not that it's a *huge* deal, but HTML-style just seems a bit better all
> > around. Yet quite a few people obviously do prefer XHTML-style. Is it
> > just for the "purity"?
> >
> > Regards,
> >
> > Simon
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> >
> >
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 
>

---------------------------------------------------------------------
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