apache / apache/lucene

extend checkJavaDocs.py to methods,constants,fields [LUCENE-4324]

Open
#5,391 10 comments 0 reactions 0 assignees View on GitHub
legacy-jira-priority:Major tool:build type:enhancement
Dominant language
Java
Stars
3.6k
Forks
1.4k
Avg merge
2d 11h
Merged PRs (30d)
88

Description

We have a large amount of classes in the source code, its nice that we have checkJavaDocs.py to ensure packages and classes have some human-level description.

But I think we need it for methods etc too. (it is also part of our contribution/style guidelines: http://wiki.apache.org/lucene-java/HowToContribute#Making_Changes)

The reason is that like classes and packages, once we can enforce this in the build, people will quickly add forgotten documentation soon after their commit when its fresh in their mind.

Otherwise, its likely to never happen.

---
Migrated from [LUCENE-4324](https://issues.apache.org/jira/browse/LUCENE-4324) by Robert Muir (@rmuir), updated Aug 28 2012
Attachments: [LUCENE-4322.patch](https://apache.github.io/lucene-jira-archive/attachments/LUCENE-4324/LUCENE-4322.patch), [LUCENE-4324_crawl.patch](https://apache.github.io/lucene-jira-archive/attachments/LUCENE-4324/LUCENE-4324_crawl.patch)

Contributor guide

Open the contributing guide

Research direction

Start with checkJavaDocs.py and review the linked LUCENE-4322.patch and LUCENE-4324_crawl.patch to understand the existing package and class checks. Extend the checker to cover methods, constants, and fields, then verify that the build enforces the documentation requirement described in the issue and contribution guidelines.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, python
Domain
build-system, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.