Saturday, August 18, 2012

Safe Reformatting of Javadoc Hyperlinks

 I was gonna write, and did write, a little piece on Safe Reformatting of Javadoc Hyperlinks. Ironically, the rendered the blog post wrong. I then clicked 'Go back to draft' or whatever it'd be called in English, because I thought I had published the thing. The saved version turned out to be blank after that. That sucked a bit.

I'll have to redo it then, and never mind the Javadoc examples that rendered wrong.

The trick is to use double quotes for your href hyperlink attribute value, not single quotes. The Eclipse Javadoc formatter will never break a doubly-quoted string, it seems. When I used single-quoted href values, the fomatter would often chop off characters from the link text one by one, and put on the next line, and also separate the "
"  would disintegrate too. With doubly quoted string, the '>' and link text will most probably end up on a new line, and be safe from chopping.
A second trick is to put spaces between the angles and the link text, e.g. '[...]> link-text
'. That will probably help with the above shredding too; the formatter will prefer to break on spaces, rather than between '<' and '/a>', which has happened to me a lot.
PS. Or somebody fix the Eclipse formatter... and while you're at it, add a better escape than @code and @literal, which don't work with '@' in the escaped text.

EDIT: Well look at that, the rendering is fuggled up again. Never mind. Here's another tip: never paste html into the blogger editor. And tip 2: edit your posts using not the blogger editor...

UPDATE: Just noticed that leaving a space before the link ('anchor') end tag makes the space be underlined; even if there is another space after the end tag. So leading space may be enough. Or no space at all, the double-quoting may be sufficient.

No comments:

Post a Comment