If you look at a module's documentation from the standard library, such as java.base, you'll see it has a section that lists which services it uses and which services it provides.

Based on the Standard Doclet's documentation, the @uses and @provides tags are how to generate the "services" section.

provides

• @provides service-type description

This tag may only appear in the documentation comment for a module declaration, and serves to document an implementation of a service provided by the module. The description may be used to specify how to obtain an instance of this service provider, and any important characteristics of the provider.

Introduced in JDK 9.

[...]

uses

• @uses service-type description

This tag may only appear in the documentation comment for a module declaration, and serves to document that a service may be used by the module. The description may be used to specify the characteristics of the service that may be required, and what the module will do if no provider for the service is available.

Introduced in JDK 9.

And you can see these tags in, for example, the source code of the java.base module. Note that it does not seem necessary for the provider implementation to be in an exported package.

However, when I try to do the same the "services" section is not generated. If I pass --show-module-contents all then the "services" section appears, but too much information is now leaked in the documentation. For instance, now the implementation class is exposed even though the class's package is not exported. The module summaries for the standard library don't do this.

What am I doing wrong? Which option do I need to pass to get this to work? Or is this a bug?

---

Reproducible Example

This example provides a dummy implementation of System.LoggerFinder. I chose that SPI because it's small and simple. But I've tried other SPIs with the same results, including:

• java.nio.file.spi.FileSystemProvider

• java.util.spi.ToolProvider

• javax.annotation.processing.Processor (from the java.compiler module)

System Info

• Java 24.0.1 (Temurin-24.0.1+9)

• Windows 10/11

Project Structure

<project-directory>
│   javac-args.txt
│   javadoc-args.txt
│
└───src
    │   module-info.java
    │
    └───com
        └───example
                DummyLoggerFinder.java

Source Code

module-info.java

/**
 * Demo module for documentation.
 * 
 * @provides java.lang.System.LoggerFinder
 */
module demo {

  provides java.lang.System.LoggerFinder with
      com.example.DummyLoggerFinder;
}

DummyLoggerFinder.java

package com.example;

/**
 * Simple SPI implementation.
 */
public class DummyLoggerFinder extends System.LoggerFinder {

  @Override
  public System.Logger getLogger(String name, Module module) {
    throw new UnsupportedOperationException("implementation not needed for demo");
  }
}

Argument Files

javac-args.txt

--module-source-path demo=src
--module demo
-Xlint:all
-Xdoclint:all
-d out/modules

javadoc-args.txt

--module-source-path demo=src
--module demo
-Xdoclint:all
-d out/docs

Build Steps

1. Compile the module (just to make sure it's valid code).

   java @javac-args.txt
   

2. Generate Javadoc.

   javadoc @javadoc-args.txt
   

Output

No output from javac.

I see the following output from javadoc:

Constructing Javadoc information...
Creating destination directory: "out/docs\"
Building index for all the packages and classes...
Standard Doclet version 24.0.1+9
Building tree for all the packages and classes...
Generating out\docs\demo\module-summary.html...
Generating out\docs\overview-tree.html...
Generating out\docs\allclasses-index.html...
Building index for all classes...
Generating out\docs\index-all.html...
Generating out\docs\search.html...
Generating out\docs\index.html...
Generating out\docs\help-doc.html...

And if I open out/docs/index.html in a browser, I do not see any "services" section in the module summary.

---

More Information

Looking into it more, the problem seems to only occur if the service type is not contained in one of the modules being documented. In other words, if the service type's module is not included in the --module argument then that service type will not be included in the "Uses" or "Provides" sections (and if that leads to no services being included in the docs, then the "Services" section will not be generated at all).

Is this intended behavior?

The problem only occurs if the service type being used or provided is not in one of the modules currently being documented by the Javadoc tool. This means any service type from an external library, including the standard library, won't be documented in the "Services" section.

I submitted a bug report and it was accepted: https://bugs.openjdk.org/browse/JDK-8362273. According to the report, it affects Java 11 to 25.