commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simon Kitching <skitch...@apache.org>
Subject Re: old style html in javadoc Was: [jira] Commented: (IO-86) Add FileFinder back into Commons IO
Date Mon, 24 Jul 2006 21:03:42 GMT
On Sun, 2006-07-23 at 21:30 -0700, Henri Yandell wrote:
> On 7/23/06, Stephen Colebourne <scolebourne@btopenworld.com> wrote:
> > The concept that XML (XHTML in this case) is human readable is highly dubious, and
has
> > become accepted wisdom far too easily.
> 
> Agreed, a .properties file is far more readable but that's not in
> question here. Bad HTML is less readable than good HTML because the
> eye is used to precompiling what's being typed.
> 
> >  The first point is that it isn't 'bad' HTML, its just normal HTML. Every HTML tool
going has to be
> > able to cope with this sort of layout so any tool arguments fail pretty quickly.
> 
> I don't agree - it was bad HTML in the mid 90s and it's bad HTML now.
> A decade of misuse doesn't make it right.
> 
> >  So it comes down to readability, which is much more of a stylistic choice. Personally,
I strive to
> > avoid unecessary clutter, only including unecessary things (eg. additionl brackets)
if I judge it
> > aids understanding.
> 
> +1.

I'm with Stephen here; simple is good. Javadoc isn't expected to be
processed by anything other than the javadoc tool, and that handles <p>
as a separator fine, so why clutter things with </p>?

Javadoc isn't really html. It's a java-specific doc format (like perl
POD etc) that happens to resemble html. There are many markup formats
that use the "separator" approach rather than the "container" approach. 

In practice, I think that either is bearable, so new files should follow
whatever convention the project already has.

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