Hi,
in Lucene and Solr we have a plugin for javac/javadoc that checks for
missing javadocs on several levels. I just checked: Solr has the
missing-doclet, too:
https://github.com/apache/solr/tree/main/dev-tools/solr-missing-doclet
But it looks like the checker is almost fully disabled and only check
for package-level javadocs (in all projects under ":solr"):
https://github.com/apache/solr/blob/f0fcd300c896b858ae83235ecdb0a109eaea5cea/gradle/documentation/render-javadoc.gradle#L107
compare Lucene, which has in most modules "class" javadocs eanbled and
often also method level docs:
https://github.com/apache/lucene/blob/411b7fd51861b77e4cf2644c02dd6c6d92011a1f/gradle/documentation/render-javadoc.gradle#L197
Uwe
Am 29.09.2023 um 01:32 schrieb Eric Pugh:
I did some searching, but didn’t find the specific reference I was hoping to
share about how to encourage good practices on a large code set…. Maybe someone
else can chime in.
Basically, what you do is run additional checks on files that have been
changed, so that as we modify a java file, if it’s missing the javadocs, then
the precommit will fail. This way we don’t need to add boilerplate everywhere
that never gets updated, which wouldn’t be helpful, but we also don’t need to
add the docs everywhere before moving forward.
JavaDocs are probably most valuable in files that actually are currently
evolving and changing, so if we have some classes that never get touched, well,
the value of adding JavaDocs to them would be the lowest presumably ;-). Over
time, the classes that are evolving and getting the most use would gain more
complete JavaDocs…
On Sep 28, 2023, at 3:33 PM, David Smiley <dsmi...@apache.org> wrote:
When I see a class without any javadocs, especially a public top level
class, it's really sad and disappointing. My colleagues have noted the
same. I'd like to see a build mechanism to up our level of standards
here. Of course we have tons of existing such classes so a solution would
have to somehow accept our current reality. Or maybe we add /**
MISSING-JAVADOC */ everywhere? Has anyone yet looked into an approach?
~ David Smiley
Apache Lucene/Solr Search Developer
http://www.linkedin.com/in/davidwsmiley
_______________________
Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 |
http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My
Free/Busy <http://tinyurl.com/eric-cal>
Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
<https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
This e-mail and all contents, including attachments, is considered to be
Company Confidential unless explicitly stated otherwise, regardless of whether
attachments are marked as such.
--
Uwe Schindler
Achterdiek 19, D-28357 Bremen
https://www.thetaphi.de
eMail: u...@thetaphi.de
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@solr.apache.org
For additional commands, e-mail: dev-h...@solr.apache.org
