You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by "Alexandre Rafalovitch (JIRA)" <ji...@apache.org> on 2016/10/19 14:36:58 UTC
[jira] [Commented] (SOLR-555) Autogenerate "user" docs about
"plugins" from code
[ https://issues.apache.org/jira/browse/SOLR-555?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15588943#comment-15588943 ]
Alexandre Rafalovitch commented on SOLR-555:
--------------------------------------------
Just as an update of the concept, I am able to get the Javadoc API to work and to generate http://www.solr-start.com/info/analyzers/ and http://www.solr-start.com/info/update-request-processors/ lists.
The challenges were that Javadoc plugins were actually broken in JDK 6 (I think) and were unusable. I got around that by using JDK 8, which is open-sourced and modifying the Javadoc source.....
Once that was done, information extraction itself is not too bad and I am actually using it to generate Solr Index for hosted Javadoc apart from the lists above.
Unfortunately, in JDK 9, this will all break again, as the Javadoc is being rewritten and - at the moment - it cannot even process straight Lucene source [JDK-8157611|https://bugs.openjdk.java.net/browse/JDK-8157611].
> 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, 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 was sent by Atlassian JIRA
(v6.3.4#6332)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org