JavaDoc Include Action

This GitHub Action replaces marked sections in Markdown with JavaDoc extracted directly from Java source. It has no third-party runtime dependencies.

Directives

Include every documented declaration in a Java file:

<!-- javadoc:all src/main/java/com/example/MyApi.java -->
<!-- /javadoc -->

Include the complete JavaDoc for one method:

<!-- javadoc:method src/main/java/com/example/MyApi.java#getApi -->
<!-- /javadoc -->

Generated content is placed between the markers. Keep the markers in the file and do not edit generated content manually. Re-running the action replaces that content and is idempotent. An overloaded method name is rejected rather than guessed.

Examples in JavaDoc

@example is a custom repeatable block tag. Its title is optional and its body is Java code. The recommended form uses {@code ...}:

/**
 * Gets the API instance.
 *
 * @example
 * {@code
 * Api api = Api.getApi();
 * }
 *
 * @example Getting a service
 * {@code
 * Service service = Api.getApi().service();
 * service.start();
 * }
 */
public static Api getApi() { ... }

This renders as an untitled Example and Example: Getting a service, each followed by a fenced java code block. Any number of @example tags may appear in one JavaDoc comment.

Usage

Place these files at the root of a dedicated action repository, then reference a version tag:

- uses: actions/checkout@v4

- name: Insert JavaDocs
  uses: STEMMechanics/javadoc-include-action@v1
  with:
    docs: 'docs/**/*.md'

The docs input is a recursive glob evaluated from the consuming repository root. The action supports descriptions, @param, @return, @throws, @exception, @since, @deprecated, @see, {@code}, {@literal}, {@link}, and common inline JavaDoc HTML.

Test locally

python3 -m unittest discover -s tests -v