: For QParser specifically, It's slightly awkward to have the class : names as the titles, esp when the majority of users may be looking for : the syntax to put in "q", not for any Java class related stuff.
not really sure how to make that better ... the classnames should be descriptive about what the plugin does, and the classname is what you need to know to register the plugin in your configs. I still expect that in addition to "programatic" docs like this, we need to beef up our "guides" for people, talking about the default usages and common cases -- places where we can say "this kind of use cases is where defType=dismax makes sense ... and then link over to these autogenerated docs for the details about what exactly this DismaxQParserPlugin does (and at the top of hte page, where you see the general docs about QParserPlugin, we would have an example of how to register custom QParserPlugin's with special names and init params and so on. : It's also a fact of life that we will need to change/add docs after a : release. How would this be done? Doc commits and doc regeneration : (with the website linking to trunk?) That works for small changes, : but what about big ones (class renames, removes, etc). That suggests : that the doc changes should also be merged onto the release-specific : branch.... more work. I'm not sure what you mean ... the docs on the trunk apply to the trunk, the docs that ship with a release apply to that release -- no different from javadocs or the tutorial today. one of the big motivations for me about trying to generate good "user" docs is that they can ship with the releases so you know exactly what plugins you've got in your version and what options they support, and we don't have to rely on special wiki markup to keep straight that a certain param wasn't added untill Solr 3.9 The wiki will certain still have it's place for "tips and tricks" and "user comments" put the primarily docs will ship with the release (and in the interest of SEO and convinient access, we can put them online in "past releases" directories just like other apache projects) : I'm fine with it going in now though... we don't actually have to : point to the generated docs if we don't want to for this release, or : we could pick and choose parts to point to from the Wiki, right? yeah ... i'll try to do this in the next few days, i need to make sure i do it in a way that plays nice with the SolrJ and contrib javadoc changes Shalin is/was doing/did (something i hadn't thought about until recently) -Hoss
