[jira] Updated: (SOLR-555) Autogenerate "user" docs about "plugins" from code

["Hoss Man (JIRA)" <ji...@apache.org>]

     [ 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

added a @solr.component taglet ... any info can be listed in it, and aqt minimum that info will show up in the javadocs (and the plugin docs) but if it contains a {@see classname} the first sentence summary of that class, and the Runtime Params for that "component" will be listed on the plugin docs as well.

need to figure out a clean way to make hyperlinking arround the plugin docs work ... wasn't really a big deal before since i was focusing on "flat" plugin docs (plugins directly listed all params inherited from their superclasses) but in the case of components you want just the summary of what the component does for people who are familiar with it; but for people that aren't, you want them to be able to click a link to learn more (without sending them to developer javadocs).


> 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, SOLR-555.patch, 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.