Commit Graph

18 Commits

Author SHA1 Message Date
Antoine Musso 7b955048eb Fix all Javadoc warnings and fail on them
This fixes all the javadoc warnings, stops ignoring doclint 'missing'
category and fails the build on javadoc warnings for public and
protected classes and class members.

Since javadoc doesn't allow access specifiers when specifying doclint
configuration we cannot set `-Xdoclint:all,-missing/private`
hence there is no simple way to skip private elements from doclint.
Therefore we check javadoc using the Eclipse Java compiler
(which is used by default) and javadoc configuration in
`.settings/org.eclipse.jdt.core.prefs` files.
This allows more fine grained configuration.

We can reconsider this when javadoc starts supporting access specifiers
in the doclint configuration.

Below are detailled explanations for most modifications.

@inheritDoc
===========
doclint complains about explicits `{@inheritDoc}` when the parent does
not have any documentation. As far as I can tell, javadoc defaults to
inherit comments and should only be used when one wants to append extra
documentation from the parent. Given the parent has no documentation,
remove those usages which doclint complains about.

In some case I have moved up the documentation from the concrete class
up to the abstract class.

Remove `{@inheritDoc}` on overriden methods which don't add additional
documentation since javadoc defaults to inherit javadoc of overridden
methods.

@value to @link
===============
In PackConfig, DEFAULT_SEARCH_FOR_REUSE_TIMEOUT and similar are forged
from Integer.MAX_VALUE and are thus not considered constants (I guess
cause the value would depends on the platform). Replace it with a link
to `Integer.MAX_VALUE`.

In `StringUtils.toBoolean`, @value was used to refer to the
`stringValue` parameter. I have replaced it with `{@code stringValue}`.

{@link <url>} to <a>
====================
@link does not support being given an external URL. Replaces them with
HTML `<a>`.

@since: being invalid
=====================

org.eclipse.jgit/src/org/eclipse/jgit/util/Equality.java has an invalid
tag `@since: ` due to the extra `:`. Javadoc does not complain about it
with version 11.0.18+10 but does with 11.0.19.7. It is invalid
regardless.

invalid HTML syntax
===================

- javadoc doesn't allow <br/>, <p/> and </p> anymore, use <br> and <p>
instead
- replace <tt>code</tt> by {@code code}
- <table> tags don't allow summary attribute, specify caption as
<caption>caption</caption> to fix this

doclint visibility issue
========================

In the private abstract classes `BaseDirCacheEditor` and
`BasePackConnection` links to other methods in the abstract class are
inherited in the public subclasses but doclint gets confused and
considers them unreachable. The HTML documentation for the sub classes
shows the relative links in the sub classes, so it is all correct. It
must be a bug somewhere in javadoc.
Mute those warnings with: @SuppressWarnings("doclint:missing")

Misc
====
Replace `<` and `>` with HTML encoded entities (`&lt; and `&gt;`).
In `SshConstants` I went enclosing a serie of -> arrows in @literal.

Additional tags
===============
Configure maven-javad0c-plugin to allow the following additional tags
defined in https://openjdk.org/jeps/8068562:
- apiNote
- implSpec
- implNote

Missing javadoc
===============
Add missing @params and descriptions

Change-Id: I840056389aa59135cfb360da0d5e40463ce35bd0
Also-By: Matthias Sohn <matthias.sohn@sap.com>
2023-06-16 01:08:13 +02:00
Matthias Sohn 1d280db147 Enable compiler option --release
This ensures the compiler compiles against the public, supported and
documented API for a specific VM version (here 11) [1]. This also means
that
we don't need EE descriptors in Eclipse anymore in order to ensure that
only supported APIs of the selected Java version can be used.

According to [2] if option --release is used --source and --target
options can't be used.

While we are at it also add default value for all new jdt core options
added in Eclipse 4.21.

[1] https://docs.oracle.com/en/java/javase/11/tools/javac.html
[2] https://docs.oracle.com/en/java/javase/14/docs/specs/man/javac.html#option-release

Change-Id: I852a5d7b0a3210751c15d79ec91915b4c01c41e2
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
2021-09-29 17:13:01 +02:00
Matthias Sohn f81a3fc91a Bump minimum required Java version to 11
Bug: 569917
Change-Id: Ifdcdb022a3f29321b4d10da1cc34acca68ed7b03
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
2021-09-29 17:12:12 +02:00
David Pursehouse 98cdca9b5a Enable and fix "Statement unnecessarily nested within else clause" warnings
Since [1] the gerrit project includes jgit as a submodule, and has this
warning enabled, resulting in 100s of warnings in the console.

Also enable the warning here, and fix them.

At the same time, add missing braces around adjacent and nearby one-line
blocks.

[1] https://gerrit-review.googlesource.com/c/gerrit/+/227897

Change-Id: I81df3fc7ed6eedf6874ce1a3bedfa727a1897e4c
Signed-off-by: David Pursehouse <david.pursehouse@gmail.com>
2019-10-17 10:20:14 +09:00
Matthias Sohn 0046b2a8fe Merge branch 'stable-5.1' into stable-5.2
* stable-5.1:
  Fix OpenSshConfigTest#config
  FileSnapshot: fix bug with timestamp thresholding
  In LockFile#waitForStatChange wait in units of file time resolution
  Cache FileStoreAttributeCache per directory
  Fix FileSnapshot#save(long) and FileSnapshot#save(Instant)
  Persist minimal racy threshold and allow manual configuration
  Measure minimum racy interval to auto-configure FileSnapshot
  Reuse FileUtils to recursively delete files created by tests
  Fix FileAttributeCache.toString()
  Add test for racy git detection in FileSnapshot
  Repeat RefDirectoryTest.testGetRef_DiscoversModifiedLoose 100 times
  Fix org.eclipse.jdt.core.prefs of org.eclipse.jgit.junit
  Add missing javadoc in org.eclipse.jgit.junit
  Enhance RepeatRule to report number of failures at the end
  Fix FileSnapshotTests for filesystem with high timestamp resolution
  Retry deleting test files in FileBasedConfigTest
  Measure filesystem timestamp resolution already in test setup
  Refactor FileSnapshotTest to use NIO APIs
  Measure stored timestamp resolution instead of time to touch file
  Handle CancellationException in FileStoreAttributeCache
  Fix FileSnapshot#saveNoConfig
  Use Instant for smudge time in DirCache and DirCacheEntry
  Use Instant instead of milliseconds for filesystem timestamp handling
  Workaround SecurityException in FS#getFsTimestampResolution
  Fix NPE in FS$FileStoreAttributeCache.getFsTimestampResolution
  FS: ignore AccessDeniedException when measuring timestamp resolution
  Add debug trace for FileSnapshot
  Use FileChannel.open to touch file and set mtime to now
  Persist filesystem timestamp resolution and allow manual configuration
  Increase bazel timeout for long running tests
  Bazel: Fix lint warning flagged by buildifier
  Update bazlets to latest version
  Bazel: Add missing dependencies for ArchiveCommandTest
  Bazel: Remove FileTreeIteratorWithTimeControl from BUILD file
  Add support for nanoseconds and microseconds for Config#getTimeUnit
  Optionally measure filesystem timestamp resolution asynchronously
  Delete unused FileTreeIteratorWithTimeControl
  FileSnapshot#equals: consider UNKNOWN_SIZE
  Timeout measuring file timestamp resolution after 2 seconds
  Fix RacyGitTests#testRacyGitDetection
  Change RacyGitTests to create a racy git situation in a stable way
  Deprecate Constants.CHARACTER_ENCODING in favor of StandardCharsets.UTF_8
  Fix non-deterministic hash of archives created by ArchiveCommand
  Update Maven plugins ecj, plexus, error-prone
  Update Maven plugins and cleanup Maven warnings
  Make inner classes static where possible
  Fix API problem filters

Change-Id: Ia57385b2a60f48a5317c8d723721c235d7043a84
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
2019-08-08 11:54:56 +02:00
Matthias Sohn 773cbb5f63 Fix org.eclipse.jdt.core.prefs of org.eclipse.jgit.junit
Use the same JDT core settings as used in org.eclipse.jgit but ignore
non-externalized strings.

Change-Id: If30013c76a197e571601a8abc882ac6a99592374
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
2019-07-24 16:21:53 +02:00
David Pursehouse 7ebd434e91 Disable Eclipse warning about unrecognized @SuppressWarnings value
The code base has several @SuppressWarnings annotations to suppress
warnings raised by Error Prone, but those are not recognized by
Eclipse and there is currently no way to tell it about them [1].

Suppress them for now.

[1] https://bugs.eclipse.org/bugs/show_bug.cgi?id=392045

Change-Id: I3de7cfa8ad4370ca5be71e1303879c73ab6829c1
Signed-off-by: David Pursehouse <david.pursehouse@gmail.com>
2018-10-17 10:40:36 +09:00
David Pursehouse a573dfc658 Enable warning for resources not managed by try-with-resource
Change-Id: Iefe97de6bdb62af558f1b0e77c9205a9186f9b4c
Signed-off-by: David Pursehouse <david.pursehouse@gmail.com>
2018-03-03 23:58:47 +01:00
David Pursehouse 3b4448637f Enable and fix warnings about redundant specification of type arguments
Since the introduction of generic type parameter inference in Java 7,
it's not necessary to explicitly specify the type of generic parameters.

Enable the warning in Eclipse, and fix all occurrences.

Change-Id: I9158caf1beca5e4980b6240ac401f3868520aad0
Signed-off-by: David Pursehouse <david.pursehouse@gmail.com>
2017-02-20 22:47:23 +01:00
David Pursehouse 7ac182f4e4 Enable and fix 'Should be tagged with @Override' warning
Set missingOverrideAnnotation=warning in Eclipse compiler preferences
which enables the warning:

  The method <method> of type <type> should be tagged with @Override
  since it actually overrides a superclass method

Justification for this warning is described in:

  http://stackoverflow.com/a/94411/381622

Enabling this causes in excess of 1000 warnings across the entire
code-base. They are very easy to fix automatically with Eclipse's
"Quick Fix" tool.

Fix all of them except 2 which cause compilation failure when the
project is built with mvn; add TODO comments on those for further
investigation.

Change-Id: I5772061041fd361fe93137fd8b0ad356e748a29c
Signed-off-by: David Pursehouse <david.pursehouse@gmail.com>
2017-02-19 20:05:08 -04:00
Matthias Sohn ab79ce91c1 Change JGit minimum execution environment to JavaSE-1.8
Bug: 500059
Change-Id: I47f3f6749a67da52029f84e002d9b155ed56d2b7
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
2016-09-20 11:32:36 +02:00
David Pursehouse 4528d5f56d Ignore 'The value of exception parameter is not used' warning
Change-Id: I50407e4a33e35b718ca40503fdd436f1f9f70fba
Signed-off-by: David Pursehouse <david.pursehouse@gmail.com>
2016-07-26 10:16:49 +09:00
Matthias Sohn c26bc63ef1 Set minimum required Java version to Java 7
Bug: 458475
Change-Id: Iea8f2236d4e6a94a8d14bb8cc685006ea3fd1bb7
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
2015-02-09 14:11:50 +01:00
Robin Rosenberg a03bdcbbb4 Don't warn for methods that can be static
Making the methods static would gain little in performance,
make the code harder to change. Removing unncessary warnings
is more important.

Change-Id: If3e6aa9c1d92e58b4e7a8e246cf4aace237d7a7b
2014-07-02 00:36:38 +02:00
Robin Rosenberg 8032b64980 Add new default settings from Eclipse 4.4
These settings were added by Eclipse simply by touching
the project settings. Adding these makes it simpler to see
what local changes have been made.

Change-Id: Iab0aa62530312eb0c78b03b5c6a632742bcc4978
2014-07-02 00:34:41 +02:00
Robin Stocker 01ebfa6c17 Disable warning about assigning to parameter
See change I08bed4275af9ec52aa4d7054067ac82f6a3c9781, where fixing such
warning lead to complaints.

If fixing is not wanted, disable it instead.

Change-Id: If31d4028fa1c6377a11e83ed5688b45701cec68b
2013-06-15 15:11:54 +02:00
Robin Rosenberg 57333a8e93 Harmonize the JDT settings within JGit
Note the the settings are slightly less restrictive for test bundles.
-Also cleanup a couple of malformed javadocs
-Update compiler warnings/errors to include default values from Juno
-We now flag diagnosed null dereference as error. We didn't do that
 earlier because of some false positives.

Change-Id: I58386d63164e65d3d8d1998da3390d99bdc7381a
Signed-off-by: Chris Aniszczyk <zx@twitter.com>
2012-11-16 10:25:45 -08:00
Shawn O. Pearce 49aac32500 Create JUnit test utilities for JGit derived sources
The LocalDiskRepositoryTestCase class is derived from the current
RepositoryTestCase code and is meant for application (or our own)
tests to subclass and access temporary repositories on the local
client disk.

Change-Id: Idff096cea40a7b2b56a90fb5de179ba61ea3a0eb
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2009-11-02 17:53:58 -08:00