search

asciidoctor / asciidoclet

:clipboard: A Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.
https://github.com/asciidoctor/asciidoclet
Apache License 2.0
133 stars 40 forks source link

resolves #3 escape annotations & process escaped closing comment #4

Closed mojavelinux closed 11 years ago

mojavelinux commented 11 years ago

This patch is by no means perfect. But it serves as a preview of how we can allow verbatim source code in the Javadoc.

It appears it's possible to process and replace the raw comment text before allowing Javadoc to parse out tags. This gives us the opportunity to substitute @ characters in front of annotation names with {@literal @} so that the developer doesn't have to dirty up the Javadoc.

Perhaps a hack. But it sure does make things nicer (see the Javadoc on Asciidoclet for an example).

johncarl81 commented 11 years ago

Sorry for the delay, looking over this now.

johncarl81 commented 11 years ago

We are handling the / and @ cases, are there any others that may be of issue?

Overall, I do like this technique. We're not disallowing the use of {@literal ..}, just allowing the end user a wider variety of easier/simpler options. We definitely need to document these shortcuts.

mojavelinux commented 11 years ago

Once again, it seems that Javadoc is extremely naive. Personally, I don't think the warning is a problem if we know that it is just a naive warning and not actually an indication that anything is going wrong.

...if you'd like to add the code used by the Pegdown doclet, that's fine with me. Really, my only concern is that we don't clobber any Javadoc. If we're sure of that, then I have no concern.

johncarl81 commented 11 years ago

After some review of the Pegdown doclet I'm still not sure what they are trying to avoid, as I get the warning with their doclet as well. I say we remove the if (!(doc instanceof PackageDoc)) { and process the package as normal, unless there is another issue with doing so.

mojavelinux commented 11 years ago

Let's just remove it, then deal with any problems as they arise. That's the best way to open source :)

johncarl81 commented 11 years ago

Rebased and merged into master. Thanks again @mojavelinux

mojavelinux commented 11 years ago

:beers: