Chris Hostetter wrote:
: Javadocs aren't appropriate for documenting configuration and RequestHandler
: parameters/usage. These are used by many non-java folks and should have
: nothing to do with the java class structure/methods/etc
i agree that the generated javadocs are not very freindly for end users,
but i think there is a lot of value in this kind of documentation living
in the code so it can be kept uptodate as the code is changed (hence my
suggestion about maybe having a custom doclet for generating a more user
freindly output of just the freeform "class" javadocs (without the methods
and package structure information)
As long as we have a consistent answer for where param/behavior docs go,
I'm happy with (almost) any convention. Perhaps all 'end-user' docs
would go under:
http://lucene.apache.org/solr/api/org/apache/solr/common/params/package-summary.html
In my view the best approach may be:
'end-user' docs (params+behavior/use cases/configuration) goes in cwiki
'plugin' overview in cwiki
'plugin' details in javadocs
Implementation details in javadocs. Javadocs should link to the
relevant cwiki page for usage.
: My thought is that nothing new would go there. Hopefully we could make the
: "sandbox" a section of cwiki with no user permissions that does not get
: included in the docs.
that's great ... but it stil leaves the MoinMoin wiki getting old,
stagnent, looking different from everything else, and requiring a
differnet syntax to be edited (like when we want to note that a param has
been deprecated in later versions of Solr or something) ... it becomes an
"image problem" to leave it up and running for very long.
In my plan, the MoinMoin wiki would be accurate for release 1.2 -- it
should stay around as long as 1.2 is a useful release. This would not
get updated docs even if they are 1.2 relevant. (unless someone REALLY
wants to update them)
As long as the pages are well marked with a warning that new stuff is on
a different site and contains a link to that site I think the image is ok.
ryan
