lucene-solr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Hoss Man (JIRA)" <j...@apache.org>
Subject [jira] Updated: (SOLR-555) Autogenerate "user" docs about "plugins" from code
Date Thu, 01 May 2008 23:42:55 GMT

     [ https://issues.apache.org/jira/browse/SOLR-555?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]

Hoss Man updated SOLR-555:
--------------------------

    Attachment: SOLR-555.patch

For the past few months, I've spent a few hours a week playing around with the javadoc doclet
and taglet APIs.  they are horrific to work with, but it cannot be denied: the ability to
hook right into the javadoc process allows you to do some fairly powerful things.

I've put together a new "SolrPluginDoclet" as well as a SolrInitParamTaglet and a SolrRunParamTaglet.
 The Doclet allows us to use the javadoc command to generate "user documentation" containing
scaled down information about all of the identified "Solr Plugin" APIs along with information
about how to use all of the implementations of those APIs found in the code base.  The Taglets
are used both by the SolrPluginDoclet when building the user docs, as well as by the standard
javadoc doclet to output more structured information about initialization and request params
that each type of plugin supports.

There are still a lot of improvements to be made (see todo list below) before i would really
consider this ready for end users -- not the least of which is actually documenting all of
our plugins using these structured javadoc tags -- but as a proof of concept i think it's
pretty cool and worth pursuing.

You can see an example of what the generated docs currently look at the URLs below.  Note
the DemoPlugin and DemoChildPlugin files in the patch which show off the custom taglet...

Traditional javadocs with new taglet added...
* http://people.apache.org/~hossman/tmp/SOLR-555/org/apache/solr/DemoPlugin.html
* http://people.apache.org/~hossman/tmp/SOLR-555/org/apache/solr/DemoChildPlugin.html

Plugin docs for User...
* http://people.apache.org/~hossman/tmp/SOLR-555/plugins.html
* http://people.apache.org/~hossman/tmp/SOLR-555/org.apache.solr.request.SolrRequestHandler.html

Todo List...
{noformat}
 *  - change output to first include a summary TOC of all classes by section,
 *    then list the actual info (standardize section header sizes)
 *  - make classes link to their full javadocs
 *  - add css+example for certain things to not display on plugin docs, just
 *    on javadocs.
 *  - make each plugin link to a wiki page with the same name (and some
 *    common prefix)
 *  - rename init.param:solr.initparam and run.param:solr.param
 *  - change param taglet to use inline @solr.type instead of @link in
 *    specific position
 *    (hmm... this is really hard .. skip for now)
 *  - make param taglets more resilient and log errors if @link for type isn't
 *    found in expected spot (might be helped by previous item if @link is
 *    replaced with @solr.type)
 *  - add a taglet for handlers to list their devault components,
 *    list params from components as well.
 *  - improve the CSS for everything so it's nice and pretty
{noformat}



> 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.


Mime
View raw message