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
