Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 368106

Summary:	Javadoc: validate HTML-code/check for HTML errors
Product:	[Eclipse Project] JDT	Reporter:	Sven Köhler <sven.koehler>
Component:	Core	Assignee:	JDT Core Triaged <jdt-core-triaged>
Status:	REOPENED ---	QA Contact:	Ayushman Jain <amj87.iitr>
Severity:	enhancement
Priority:	P3	CC:	amj87.iitr, lrozenblyum
Version:	3.7.1	Keywords:	helpwanted
Target Milestone:	---
Hardware:	PC
OS:	All
Whiteboard:

Description Sven Köhler

2012-01-08 10:54:43 EST

Build Identifier: 

I validated the javadoc HTML files generated for a large project I joined (right click on folder in eclipse -> validate, it's a feature of WTP I think). It turned out, that beside some errors caused by the javadoc itself (invalid meta tags), badly written HTML is simply copied from the javadoc comments into the HTML files generated by javadoc.

Here's a list of bad HTML which I encountered so far in javadoc comments:

@param abc The parameter <code>abc<code> must be larger than zero
=> error because <code> is improperly closed

@param angle Angle to rotate, is allowed to be >360 degrees
=> error because of unescaped > character (>360 should be &gt;360)

<pre>int x = y << 7;</pre>
=> error because of unescaped < character (<< should be &lt;&lt;)

I guess more bad things are possible (improperly escaping the & character for example).


Currently, Eclipse does not seem to validate HTML used in javadoc comments.
It would be a great enhancement, if Eclipse could check for obviously broken HTML code. Especially since the javadoc tool doesn't do any checking/conversion of broken HTML into proper HTML, the status quo seems to be that the programmer himself has to make sure his HTML-code is correct. Eclipse could be of great help here.

Reproducible: Always

Comment 1 Ayushman Jain

2012-01-08 12:28:58 EST

Checking for HTML syntax is out of scope for the java compiler. This should be done by another plugin which can validate the HTML code, and not JDT. JDT already offers validation for javadoc through Preferences>Compiler>Javadoc, but for HTML you can use plugins such as EclipseTidy - http://eclipsetidy.sourceforge.net/

Comment 2 Sven Köhler

2012-01-08 13:29:52 EST

I'm reopening, because I'm not sure whether your response is appropriate. Maybe you just have to rephrase your answer or maybe reassign to a different team (WTP?).

The problem I reported was about HTML _inside_ javadoc comments. Unfortunately, javadoc relies on HTML for certain tasks. That of course doesn't mean that JDT has to understand HTML.

At first glance, I cannot tell whether eclipsetidy supports validation of the HTML inside javadoc comments. I will install it and check whether that is the case. However, if that is not the case, there is certainly an open problem here! Probabaly it is in deed not supposed to be solved by the JDT team.

May I suggest a cooperation between WTP and JDT? Because HTML validation is already included in WTP, and actually extracting the javadoc comments from Java source files might actually rely on code from JDT. So in conclusion, the two can probably solve this by cooperation. Also, I'd like to see the HTML right in front of me, while I'm editing the Java source file.

Also consider, that this problem might be inbetween the scope of WTP and JDT:
- WTP focuses on HTML/PHP (no Java)
- JDT focuses on Java (no HTML)

So I'm not sure who this should be assigned too.

Comment 3 Ayushman Jain

2012-01-08 14:15:19 EST

I meant you can use the EclipseTidy plugin to validate the generated HTML. If you want to do it in the java editor, the best bet is another plugin which can use extensions of both WTP and JDT plugins to parse and validate HTML inside javadocs. The fact that this problem cannot be solved by either plugin independently itself makes a case for a new plugin. 

> May I suggest a cooperation between WTP and JDT? 
That will introduce dependencies between the two plugins, which is a no go.

I intend to close as WONTFIX again, not because this problem cannot be fixed, but because neither WTP or JDT can fix it independently.

Comment 4 Sven Köhler

2012-01-08 15:15:11 EST

(In reply to comment #3)
> I meant you can use the EclipseTidy plugin to validate the generated HTML.

I use WTP to validate the generated HTML, and it's awful pain searching the Java source/method which results in the error in the HTML file.

> If
> you want to do it in the java editor, the best bet is another plugin which can
> use extensions of both WTP and JDT plugins to parse and validate HTML inside
> javadocs. The fact that this problem cannot be solved by either plugin
> independently itself makes a case for a new plugin. 

I agree.

> > May I suggest a cooperation between WTP and JDT? 
> That will introduce dependencies between the two plugins, which is a no go.

I see.

> I intend to close as WONTFIX again, not because this problem cannot be fixed,
> but because neither WTP or JDT can fix it independently.

Is there no way keeping this open? I understand, that this cannot survive as a request for enhancement of JDT/WTP. So is there no way of keeping this as an RFE asking for a new plugin?

Comment 5 Ayushman Jain

2012-01-09 03:15:33 EST

The Eclipse bugzilla is only for bugs/RFEs for projects in the Eclipse ecosystem. Work on a plugin project can be done separately and the plugin can be pushed onto the Eclipse Marketplace. You can canvass support for such a plugin on social forums online, or blogposts. There's no point letting it linger on bugzilla because its currently not a bug/REF against an Eclipse project. Thanks!

Comment 6 Ayushman Jain

2012-01-09 05:55:23 EST

On second thoughts, keeping this open in case someone decides/wants to contribute such a functionality to JDT. 
PS: WTP should not be used.