[ https://issues.apache.org/jira/browse/SOLR-3904?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13566139#comment-13566139 ]
Commit Tag Bot commented on SOLR-3904: -------------------------------------- [trunk commit] Chris M. Hostetter http://svn.apache.org/viewvc?view=revision&revision=1440263 SOLR-3904: package.html for all packages in solr-core > 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.2, 5.0 > > 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: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org