How to properly lint javadoc with vale ?

[marcwrobel]

I am trying to configure vale for a java project to lint the javadoc but I can't make it work. Note that the Javadoc format is similar to HTML.

I used the RedHat package as a starting point with the following configuration :

StylesPath = .vale/styles
Vocab = jbanking
MinAlertLevel = warning

[*.md]
BasedOnStyles = RedHat

# Ignore code surrounded by backticks or plus sign, parameters defaults, URLs.
TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[)

[*.java]
BasedOnStyles = RedHat

When I try to validate the following class :

package fr.marcwrobel.jbanking;

import java.util.Optional;

/**
 * The countries, dependent territories, and special areas of geographical interest having an
 * <a href="https://wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements">Officially assigned</a> ISO 3166-1
 * code, <a href="https://www.iso.org/iso-3166-country-codes.html">as defined by International Organization for
 * Standardization</a>.
 *
 * <p>
 * One exception has been made for Kosovo. Kosovo has a user-assigned code, XK, that is being used temporarily by the European
 * Commission, the IMF, and SWIFT.
 *
 * <p>
 * Note that enum entries are named after the ISO 3166-1 alpha-2 code. This choice has been made in version 3.0.0 of jbanking in
 * order to :
 *
 * <ul>
 * <li>reduce breaking changes in future versions (names change more often than codes),
 * <li>make this enum easier to serialize (to JSON, in database...),
 * <li>prevent accidental duplicates.
 * </ul>
 *
 * <p>
 * Last verification date of this list can be seen in the {@code @LastVerification} value.
 *
 * <p>
 * Usage:
 *
 * <pre>
 * // Get ISO country information
 * IsoCountry country = IsoCountry.fromAlpha2Code("FR").get();
 * Assertion.assertEquals("FRA", country.getAlpha3Code());
 * Assertion.assertEquals(250, country.getNumericCode());
 * Assertion.assertTrue(country.isIndependent());
 * Assertion.assertTrue(country.isParticipatingTo(EUROPEAN_ECONOMIC_AREA));
 * </pre>
 *
 * @see <a href="https://www.iso.org/iso-3166-country-codes.html">ISO 3166 Country Codes</a>
 * @since 1.0
 */
public class Test {

  /**
   * Returns the country on which this country depends.
   *
   * <p>
   * Note that the dependency link between two countries :
   *
   * <ul>
   * <li>is based on information provided by the <a href="https://www.iso.org">International Organization for Standardization
   * (ISO)</a>,
   * <li>may be unspecified, mainly for political reasons,
   * <li>can take <a href="https://en.wikipedia.org/wiki/List_of_sovereign_states">many forms</a> : free association, territory,
   * special administrative region... (this is outside the scope of jbanking).
   * </ul>
   *
   * @return an {@link IsoCountry} encapsulated in an {@link Optional}, or {@link Optional#empty()}
   * @since 2.1.0
   */
  public Optional<IsoCountry> getDependency() {
    return null;
  }

}

I got the following errors :

 src/main/java/fr/marcwrobel/jbanking/Test.java
 8:31   warning  Use either 'or' or 'and' in     RedHat.Slash              
                 'org/wiki'                                                
 9:31   error    Use 'ISO' rather than 'iso'.    RedHat.CaseSensitiveTerms 
 9:35   warning  Use either 'or' or 'and' in     RedHat.Slash              
                 'org/iso'                                                 
 9:39   error    Use 'ISO' rather than 'iso'.    RedHat.CaseSensitiveTerms 
 42:30  error    Use 'ISO' rather than 'iso'.    RedHat.CaseSensitiveTerms 
 42:34  warning  Use either 'or' or 'and' in     RedHat.Slash              
                 'org/iso'                                                 
 42:38  error    Use 'ISO' rather than 'iso'.    RedHat.CaseSensitiveTerms 
 54:71  error    Use 'ISO' rather than 'iso'.    RedHat.CaseSensitiveTerms 
 57:49  warning  Use either 'or' or 'and' in     RedHat.Slash              
                 'org/wiki'                                                

✖ 5 errors, 4 warnings and 0 suggestions in 1 file.

All those warnings / errors are located in HTML links. Is there a way to exclude the linting of the href attribute ? Is there a "standard" configuration to use when linting javadoc with vale ?

[marcwrobel]

I tried to configure vale to treat Javadoc as HTML (I was inspired by https://vale.sh/docs/topics/scoping/#types-formats-and-scopes) but I failed. I used the following configuration :

[formats]
java = html

[*.{html,java}]
BasedOnStyles = RedHat

I also tried to use TokenIgnores but it did not work :

TokenIgnores = (href="http[^\n]+")

[jdkato]

Javadoc isn't a supported format, so there's not going to be a perfect way to do this.

[marcwrobel]

OK, thank you @jdkato.

Is there a way to at least ignore URLs contained in the href attributes of a tags using TokenIgnores ? I have read #320 and it mentionned #249, which is now closed. But I do not know if it applies to my use case.

[jdkato]

Ignore patterns only work in supported formats.