lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Robert Muir (JIRA)" <j...@apache.org>
Subject [jira] Commented: (SOLR-2379) Improve documentation of Analyzers and Tokenizers
Date Fri, 25 Feb 2011 14:01:38 GMT

    [ https://issues.apache.org/jira/browse/SOLR-2379?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12999360#comment-12999360
] 

Robert Muir commented on SOLR-2379:
-----------------------------------

{quote}
Few of the TokenFilterFactories are documented at all. Some of them have a simple XML config
snippet example. Take the StandardTokenFilterFactory. It had no class JavaDoc until two days
ago, when Koji and yourself added an xml snippet.
{quote}

Thats not really correct: typically they have a link to the tokenfilter, for example here
is ThaiWordFilterFactory.
(Factory for {@link ThaiWordFilter}). if they take arguments, then typically they describe
what those arguments do.

This is enough, because someone can click the ThaiWordFilter and get all the details there.


The javadocs for the factory need only document the factory.

{quote}
I think a reasonable goal, at least for these plugin type of classes, is to use the JavaDoc
as the official main doc and point from Wiki to there. But then the Class-level JavaDoc must
give a short introduction to what the filter does, when it is typically used along with a
list of all valid parameters and their values.
{quote}

I really don't think we should duplicate documentation from any Tokenizers/Filters into the
factories. The factory should just have a javadoc ref to what it produces, and explain its
various parameters. In other words, it need only document itself. 

Any other documentation is actually redundant and problematic, as long as this javadoc exists
it increases the maintenance load around here with no benefits to the user at all.



> Improve documentation of Analyzers and Tokenizers
> -------------------------------------------------
>
>                 Key: SOLR-2379
>                 URL: https://issues.apache.org/jira/browse/SOLR-2379
>             Project: Solr
>          Issue Type: Improvement
>          Components: documentation
>            Reporter: Jan H√łydahl
>            Priority: Minor
>              Labels: wiki
>
> See thread http://search-lucene.com/m/S7l5XMQ8iA1
> The Wiki page http://wiki.apache.org/solr/AnalyzersTokenizersTokenFilters as well as
http://wiki.apache.org/solr/LanguageAnalysis are not up to date with current state.

-- 
This message is automatically generated by JIRA.
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message