better place to add the rendering code

[GoogleCodeExporter]

at the moment your rendering code is commentTagsToString; it is better to
put it in printCommentTags.

the reason is because commentTagsToString is called repeatedly and
sometimes recursively - eg. it is called for the taglets in each comment,
then the output form of the taglet is embedded into the original comment,
and the whole thing is passed through commentTagsToString again. this
results in some parts of the comment being rendered twice; depending on
markdown syntax this may or may not be a problem, but can easily be avoided
by using the fix i suggested.

i came across this problem when i was coding a doclet of my own - see
http://github.com/infinity0/bliki-doclet/tree/master

(since MediaWiki syntax does not treat a list item that is spread over
several lines as one single block, i had to add some of my own code to
automatically merge some lines into single lines. this involved calculating
and removing indents on the lines.

if i added the rendering code into commentTagsToString, everything after an
{@inheritDoc} declaration would fail to render. the inherited document
would be passed through commentTagsToString first, then re-added into the
original comment. this screwed up my indentation calculation, which meant
that the lines after the {@inheritDoc} all had 1 extra space on the left,
which to MediaWiki means "pre-formatted block".)

anyway, after seeing your doclet, i'd say i prefer markdown more than
MediaWiki, for javadoc comments anyway. however, there is (at least) one
major bug in the MarkdownJ implementation which means i can't use it -
MarkdownJ doesn't ignore UPPERCASE html tags, like the ones javadoc
generates. if you add a {@link Class} to your javadoc comment, and pass it
through markdown-doclet, it will... well, see for yourself.

it's already a marked issue in MarkdownJ, though, so hopefully it will be
resolved at some point in the future.

one other thing is, i think it's untidy to copy source code from other
repositories statically - you should write scripts to generate the source
code for markdown-doclet instead, like i did for my bliki-doclet. that way,
you don't need to keep adapting your code as it changes.

Original issue reported on code.google.com by infinity0x@gmail.com on 30 Jul 2009 at 6:11

[GoogleCodeExporter]

Thanks, I didn't see this til now - a lot of good points.

I've fixed the {@link} issue you mentioned (a workaround for MarkdownJ) but 
will take a 
look at the other things when I get a chance.

Original comment by tibe...@gmail.com on 17 Sep 2009 at 1:54

• Changed state: Accepted

[GoogleCodeExporter]

Tried other suggested change and had mixed results. Will stick with current
implementation for now.

Original comment by tibe...@gmail.com on 22 Apr 2010 at 7:42

• Changed state: Fixed