[
https://issues.apache.org/jira/browse/SOLR-3904?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Robert Muir updated SOLR-3904:
------------------------------
Attachment: SOLR-3904_buildxml.patch
Here's the patch that would enforce all packages have package.html (at least
one sentence describing the package).
Note this macro takes level=class or level=method as well (so you can improve
it as you go).
For more examples see lucene's documentation-lint task in its build.xml (there
you can see we enforce level="class" across the board, but as we clean up
certain areas of the codebase we "lock them in" at level=method, and hopefully
eventually just have one line saying level="method"... iterative development).
finally, it can be too frustrating to run documentation-lint over and over
again when trying to fix this stuff (its slowish), so i tend to iterate locally
with a workflow like this (imagine i was fixing solrj):
{noformat}
rmuir@beast:~/workspace/lucene-trunk/solr/build/docs/solr-solrj$ python3
~/workspace/lucene-trunk/dev-tools/scripts/checkJavaDocs.py . package
<this is really fast>
<fixup some javadocs in solrj and run 'ant javadocs' from solrj/ which is also
fast>
<run the python script again until its happy>
<then finally before committing run precommit (which will call the slow
documentation-lint)>
{noformat}
> add package level javadocs to every package
> -------------------------------------------
>
> Key: SOLR-3904
> URL: https://issues.apache.org/jira/browse/SOLR-3904
> Project: Solr
> Issue Type: Improvement
> Components: documentation
> Reporter: Hoss Man
> Assignee: Hoss Man
> Fix For: 4.1
>
> Attachments: SOLR-3904_buildxml.patch
>
>
> quoth rmuir on the mailing list...
> {quote}
> We've been working on this for the lucene side (3.6 was the first
> release where every package had docs, 4.0 will be the first where
> every class had docs, and we are now working towards
> methods/fields/ctors/enums).
> I think this would be valuable for solr too (especially solrj as a start).
> Besides users, its really useful to developers as well. Of course we
> all think our code is self-documenting, but its not always the case. a
> few extra seconds can save someone a ton of time trying to figure out
> your code.
> Additionally at least in my IDE, when things are done as javadoc
> comments then they are more easily accessible than code comments. I'm
> sure its the case for some other development environments too.
> Filling in these package.html's to at least have a one sentence
> description would be a really good start. It lets someone know where
> to go at the high-level.
> If I was brand new to solr and wanted to write a java app that uses
> solrj, i wouldn't have a clue where to start
> (https://builds.apache.org/job/Solr-Artifacts-4.x/javadoc/solr-solrj/index.html).
> 12 sentences could go a really long way.
> And for all new code, I hope we can all try harder for more complete
> javadocs. when you are working on something and its fresh in your head
> its a lot easier to do this than for someone else to come back around
> and figure it out.
> {quote}
> I'm going to try and make it a priority for me to fill in package level docs
> as we look towards 4.1
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
