JavaDoc and HTML version

[Stefan Ram]

I used to believe that JavaDoc comments had to be written in
version 3.2 of HTML. But now I read:

»You can use whichever version of HTML your browser supports«

http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html

Is XHTML (1.0, 1.1, 2.0) a HTML version in this sense?

Is HTML 5.0 a HTML version in this sense?

Doesn't this reduce the interoperability of Java source code,
compared to a JavaDoc, where everyone is required to use a
specific HTML version?

For example, HTML element type names may have different
meanings in different HTML versions. When such an element is
used in JavaDoc, how can an interpreter of the source file
(human or machine) know, which meaning is intended (as there
is no way to specify the HTML version used).

Maybe it is Swing, where version 3.2 of HTML is required and
I have confused this with JavaDoc.

 

[Arne Vajhøj]

I used to believe that JavaDoc comments had to be written in
version 3.2 of HTML. But now I read:

»You can use whichever version of HTML your browser supports«

http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html

Is XHTML (1.0, 1.1, 2.0) a HTML version in this sense?

Is HTML 5.0 a HTML version in this sense?

Doesn't this reduce the interoperability of Java source code,
compared to a JavaDoc, where everyone is required to use a
specific HTML version?

For example, HTML element type names may have different
meanings in different HTML versions. When such an element is
used in JavaDoc, how can an interpreter of the source file
(human or machine) know, which meaning is intended (as there
is no way to specify the HTML version used).

Maybe it is Swing, where version 3.2 of HTML is required and
I have confused this with JavaDoc.

All the JavaDoc has a DOCTYPE in the top, so I would assume that
the HTML markup is valid against that.

If someone generate JavaDoc that is not compatible with that
version, then they should change the DOCTYPE to match.

Besides I don't think the problem is that big. The generated
HTML is rather simple so it is most likely compatible with
any HTML version.

Arne

 

[Roedy Green]

Besides I don't think the problem is that big. The generated
HTML is rather simple so it is most likely compatible with
any HTML version

I don't think it is so much the generated HTML that is the problem. It
is the programmer-written embedded HTML.

I ran the generated Javadoc HTML through HTMLValidator and hundreds of
errors came crawling out. It is pretty rough in compliance.

There is a fundamental problem with using HTML in Javadoc comments.

The embedded Javadoc becomes harder to read for the programmer the
nicer it looks to someone perusing the generated HTML Javadoc.

I have pondered how to fix the problem.

1. Teach the IDEs to render the Javadoc as HTML, with a Dreamweaver
type editor for it.

2. Use a text layout style that gets converted to HTML, inserting
entities and simple tags.

3. Use some alternate Unicode chars for < > that don't need entities
so they are readable in both Javadoc and HTML. I got nailed the other
day having to use &lt; &gt; using the wrong entity. The error does
not stand out like a sore thumb it would if you used < >.
--
Roedy Green Canadian Mind Products
http://mindprod.com

"If people become accustomed to lying, they will unconsciously commit every possible wrong deed. Before they can act wickedly, they must lie, and once they begin to lie they will act wickedly without concern."
~ Gautama Buddha

 

[Arne Vajhøj]

I don't think it is so much the generated HTML that is the problem. It
is the programmer-written embedded HTML.

But that is fully under the control of the developers. I can not
see a problem.

BTW, in my experience the embedded HTML is usually rather simple.

There is a fundamental problem with using HTML in Javadoc comments.

The embedded Javadoc becomes harder to read for the programmer the
nicer it looks to someone perusing the generated HTML Javadoc.

I have pondered how to fix the problem.

I think it is a non-existing problem you are trying to solve.

Arne

 

[Roedy Green]

There is a fundamental problem with using HTML in Javadoc comments.

I think it is a non-existing problem you are trying to solve.

I don't think you understand the problem. You jumped to conclusions
about what I was going to say without actually reading it.
--
Roedy Green Canadian Mind Products
http://mindprod.com

"Everybody’s worried about stopping terrorism. Well, there’s a really easy way: stop participating in it."
~ Noam Chomsky

 

[Mike Schilling]

I don't think you understand the problem. You jumped to conclusions
about what I was going to say without actually reading it.

Since I've never seen programmer-written HTML that goes much beyond <b>,
<i>, and <p>, I don't think there's much of an issue either.

 

[Lew]

Since I've never seen programmer-written HTML that goes much beyond <b>,
<i>, and <p>, I don't think there's much of an issue either.

Also common: &lt; &gt; <code> <br>

The JLS first edition specifies that "the specific markers <H1>, <H2>, <H3>,
<H4>, <H5>, <H6>, and <HR> are reserved for use by the documentation generator
and should not be used in the text", and refers to "the document 'Hypertext
Markup Language -Version 2.0' by T. Berners-Lee and D. Connolly[, which] may
be found as RFC1866".

"(This chapter was removed from the second edition.)" [1]

I'm pretty sure that these days Javadoc supports HTML 3.2, but I can't find a
reference for that just now.

[1]
<http://java.sun.com/javase/6/docs/technotes/tools/solaris/javadoc.html#documentation>

 

[Mike Schilling]

Also common: &lt; &gt; <code> <br>

Sure. The result is still that it'll work with any modern browser.