[
https://issues.apache.org/jira/browse/SOLR-555?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12602792#action_12602792
]
Hoss Man commented on SOLR-555:
-------------------------------
bq. Hoss - have you tried XDoclet?
When i first started experimenting with this idea, i assumed a javadoc doclet
would make the most sense .. then i tried making one, and i gave up because it
has, by far, the worst "API" I've ever used in my life (caveat: i'm refering
solely to Java APIs when i make that statements). So then i started looking at
existing third party javadoc doclets, hoping to find a nice one that would
already extract all of the useful info into XML so i could use XSLT (there was
one, but it's really old and couldn't handle some pretty basic stuff) and then
i started looking at other technologies. After experimenting with many of
them, I went back and revisited the javadoc doclet approach: came to grips with
the cluster f*ck of an API, ignoring the parts of it that were truly abhorent,
and using only the core pieces that were really needed (my first attempt was
trying to subclass the standard doclet to acutally incorperate the new pages
into the existing javadoc navigation) which lead me to the current patch.
XDoclet, XDoclet2, and QDox (the java parser that XDoclet2 uses) were all on
that list of other technologies, i don't remember specifically why i decided
not to go with them, but one of the broader issues with most alternate
solutions was that since they used *good* APIs for doing things, they couldn't
be hooked into normal javadocs -- one of my goals is to try and get to the
point where developers write one "doc" for each plugin, it lives in the code
and is displayed both in the javadocs for the plugin, as well as in the scaled
down "user" docs that this would generated. generating "user" documentation
about a plugin using something like XDoclet probably would have been easy --
but to get the same information included in the "developer" javadocs would
require just as much orthoginal Taglet work as i'm doing now -- and simple
things like [EMAIL PROTECTED] tags in the body of a javadoc comment wouldn't
work automaticly with XDoclet2 (at least: not as far as i can tell)
XDoclet2 certianly seems like the best way to auto generate information from
java *code* but for processing javadoc comments, i (unfortunately) couldn't
find many solutions better then javadoc doclets and taglets.
> Autogenerate "user" docs about "plugins" from code
> --------------------------------------------------
>
> Key: SOLR-555
> URL: https://issues.apache.org/jira/browse/SOLR-555
> Project: Solr
> Issue Type: Improvement
> Reporter: Hoss Man
> Assignee: Hoss Man
> Attachments: SOLR-555.patch
>
>
> Our current strategy of using javadocs for "developer" documentation and the
> wiki for documenting "user" features only gets us so far -- among other
> things, it makes it hard to include the "user" documentation in our releases,
> but it also results in a disconnect between when code changes and when
> documentation gets updated.
> in an ideal world, "user" documentation would live in the code right along
> side the implementation, just like with javadocs -- but the standard set of
> information displayed by javadocs isn't very user friendly. we should find a
> better way to allow us to "edit" the info about how to use a plugin right
> along side the code for that plugin and generate user friendly documentation
> from that.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
