[
https://issues.apache.org/jira/browse/LUCENE-7964?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16159440#comment-16159440
]
Hoss Man commented on LUCENE-7964:
----------------------------------
{quote}
I think it is more important to document all parameters and their valid values
than to give one specific example of how to setup a complete analyzer. We could
add a
{noformat}
<dl><dt>myparam</dt><dd>description</dd><dt>myparam2</dt><dd>desc</dd></dl>…
{noformat}
to each, along with a standard phrase:
"See CustomAnalyzer (link) for an example of how to create an Alalyzer with
this filter”
{quote}
FWIW: as things stand right now, the ref-guide tries it's best to "summarize"
the key options available and show a valid example -- but still links to the
javadocs for every factory for completeness (and is prone to getting out of
sync since people have to remember to manually update both the javadocs and the
ref-guide) ... so the examples of syntax in the javadocs are still handy, but
as we move away from hand editing schema.xml (and towards the schema api) they
will obviously become less useful over time.
----
Long, Loooong, ago i experimented with the idea of using custom javadoc doclet
markup to try and create a way for solr plugins (like these factories) to be
able to declare the diff params (and each params datatype) that they supported
in a "structured" way that could then be used in both the "javadocs" for
developers as well as in some new custom formatted "plugin docs" for non-tech
solr users that would omit most of the constructor/method details of regular
javadocs: SOLR-555
I eventually got frustrated with how cumbersome the javadoc APIs were to try
and deal with (customizeing required a lot of assumptions about sun internal
classes) and just abandoned the whole approach.
I have no idea what the state of the art is in that regard -- i know
[~arafalov] did some interesting stuff to power his solr-start.com site (see
latest comments in SOLR-555) -- but in general, it would be really great if we
could get the basic info about the options supported by each factory not just
into a consistent HTML table format in the javadocs, but also in something
easily machine parsable -- then the new ref-guide build process could easily
parse & auto-generate the equivilent asciidoc syntax info in the ref-guide.
left field idea: what if we created a simple json/xml formated file that we
kept in the source tree along with all of these factories that specified a
short description of the factory, all the params supported along with, their
data types, and some basic example values + some sample input/output values --
these data files could then be used by:
# a unit test that uses SPI to get a list of all factories, verifies that evey
factory has a corrisponding data file, that the sample params don't cause any
errors, and that feeding the sample input produces the sample output
# the documentation ant task which could generate an HTML snippet file from
each for inclusion by the javadocs of each class (the doc linter could confirm
the class javadocs for every class with a data file already has the neccessary
\@include)
#* as a special case, a snippet indended for inclusion in the CustomAanalyzer
javadocs could be generated showing how some of the notable factories can be
chained together
# the ref guide build, which could use the datafiles to generate asciidoc
syntax for inclusion in the appropriate places in the ref guide -- and which
could error if a new factory gets added but there isn't an include reference to
it in any of the ref-guide sections.
> Remove Solr fieldType XML example from Lucene AnalysisFactories JavaDoc
> -----------------------------------------------------------------------
>
> Key: LUCENE-7964
> URL: https://issues.apache.org/jira/browse/LUCENE-7964
> Project: Lucene - Core
> Issue Type: Improvement
> Components: general/javadocs
> Reporter: Jan Høydahl
> Priority: Trivial
> Fix For: 7.1
>
>
> As proposed and discussed in this dev-list thread:
> https://lists.apache.org/thread.html/9add7e4a3ad28b307dc51532a609b423982922d734064f26f8104744@%3Cdev.lucene.apache.org%3E
> [~rcmuir] [~dsmiley] [~thetaphi]
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
