New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix error messages from Javadocs #4191

Merged
merged 1 commit into from May 10, 2016

Conversation

Projects
None yet
3 participants
@GKFX
Contributor

GKFX commented Dec 6, 2015

I'm trying to significantly reduce the number of error messages from the ant doc command, so that the genuine errors can be seen and dealt with. Currently, for example, there's an unclosed bold tag over a lot of an online Javadoc page. (It seems to have been fixed in the original files now though.)

This isn't finished yet; I'd like some advice. This first commit was just running GenerateDescriptions.py with some patching/manual editing of files where it was broken. This was so that if I needed to modify and rerun the script or XMLs later, the later commits' diffs wouldn't contain ordinary updates to XML files.

The second commit fixes most of the errors except those in the HTML and syntax categories of Javadoc's Doc-lint tool, and suppresses the production of those messages by the Javadoc tool. It also makes the @usage and @brief tags display in the proper Javadoc, since that was an option I had when stopping them from being errors; I can hide them if preferred.

This just leaves the syntax errors. As far as I can tell, there's no way to stop Javadoc moaning about <br /> but keep getting the useful messages about unclosed tags and other real errors. And there are loads of messages about <br />, making Javadoc's output almost unreadable if you don't suppress them. So: can I

  • modify all the XML files to make them say <br> as preferred?
  • modify the script to convert <br /> to <br>?
  • or just leave it alone and keep all syntax errors suppressed?

I'm asking because I don't know what else uses those files and how strict their XML needs to be. I'd also need to wrap code samples in the XMLs in {@code } tags where they contain angle brackets (which escapes them) to avoid filling the doc comments in the .java files with &lt;&lt;=; can all other users of the XML files handle that sort of Javadoc syntax?

@benfry

This comment has been minimized.

Show comment
Hide comment
@benfry

benfry Feb 13, 2016

Member

If you'll remove the 'regenerate javadocs' commit from this PR, then I can merge it. The other stuff might be fine, but re-running those scripts needs to be handled by @REAS, so that's something we should coordinate separately with him.

Member

benfry commented Feb 13, 2016

If you'll remove the 'regenerate javadocs' commit from this PR, then I can merge it. The other stuff might be fine, but re-running those scripts needs to be handled by @REAS, so that's something we should coordinate separately with him.

@GKFX

This comment has been minimized.

Show comment
Hide comment
@GKFX

GKFX Feb 17, 2016

Contributor

Okay, I've done that.

Contributor

GKFX commented Feb 17, 2016

Okay, I've done that.

@REAS

This comment has been minimized.

Show comment
Hide comment
@REAS

REAS Feb 17, 2016

Member

@GKFX All of the
in the XML files are
to work with the system, but nothing has been automated. We've put so much time and energy into getting this to work over the years, but as you've seen it's not finished.

Member

REAS commented Feb 17, 2016

@GKFX All of the
in the XML files are
to work with the system, but nothing has been automated. We've put so much time and energy into getting this to work over the years, but as you've seen it's not finished.

@benfry

This comment has been minimized.

Show comment
Hide comment
@benfry

benfry May 8, 2016

Member

@GKFX Thanks for your follow-up. Can you redo your branch so that it no longer has conflicts? Sorry to have missed the window to get it merged earlier.

Member

benfry commented May 8, 2016

@GKFX Thanks for your follow-up. Can you redo your branch so that it no longer has conflicts? Sorry to have missed the window to get it merged earlier.

@GKFX

This comment has been minimized.

Show comment
Hide comment
@GKFX

GKFX May 10, 2016

Contributor

@benfry I've rebased it.

Contributor

GKFX commented May 10, 2016

@benfry I've rebased it.

@benfry benfry merged commit eb0429a into processing:master May 10, 2016

@benfry

This comment has been minimized.

Show comment
Hide comment
@benfry

benfry May 10, 2016

Member

Thanks again!

Member

benfry commented May 10, 2016

Thanks again!

@benfry

This comment has been minimized.

Show comment
Hide comment
@benfry

benfry May 10, 2016

Member

Merged for 3.1.1, fixes #1492

Member

benfry commented May 10, 2016

Merged for 3.1.1, fixes #1492

@GKFX GKFX deleted the GKFX:javadocs branch Aug 29, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment