Interesting stuff... and immediately applicable since I need to doc the QParser stuff. http://people.apache.org/~hossman/tmp/SOLR-555/plugins/org.apache.solr.search.QParserPlugin.html
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. 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 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? -Yonik On Thu, Jul 31, 2008 at 7:11 PM, Chris Hostetter <[EMAIL PROTECTED]> wrote: > > I'd hoped to be long done with SOLR-555 by now, have it all polished and > spiffy and committed ... but it's not. > > The meat is there, it functions and does everything i want it to do, the > only reasons I've been hesitent to commit are: > 1) Some of the internals are a bit kludgy > 2) It doesn't do a lot of error checking / warning about the new custom > javadoc tags being used improperly. > 3) The html pages currently created aren't very pretty > 4) Is there anypoint in rushing it? Will we realy try to fill in some > good user docs prior to 1.3 if we commit this now? > > #1 probably isn't that big of deal since it's only a build tool. End users > never run it, we don't really need to worry about users extending it, etc... > i can make it better later if/when i have time, but unless somebody else > thinks it's really a bad idea, this isn't a show stopper. > > #2 would be nice to take care of since nobdy is perfect and getting warnings > about documentation glitches is a nice way to spot them ... but we shouldn't > refrain from using a tool that makes writing documentation we don't have > easier just because it won't neccessarily warn us when there is a mistake in > our docs. (again: unless anyone has a strong opinoin, not a show stopper) > > #3 and #4 are really the only big questionable things ... is it worth it to > start using this, and start generating better documentation that we can > include in 1.3 even if the documentation isn't pretty to look at? Will we > take the time before releasing to fill in the documentation so it's actually > useful? ... or should we hold off, stick with the status quo (all "user" > docs are in wiki pages) and worry about after 1.3? > > > ? > > -Hoss > >
