Skip to content

Support Spring-Modulith-native extraction of Javadoc into Application Module Canvases #854

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
odrotbohm opened this issue Oct 3, 2024 · 0 comments
Assignees
Labels
in: documentation support Documentation generation type: enhancement Major enhanvements, new features
Milestone

Comments

@odrotbohm
Copy link
Member

Our documentation feature already supports including Javadoc extracted from the source code through the Spring Auto RESTDocs doclet. That, unfortunately, has been discontinued. Furthermore, it has always been a stretch having to set up a completely unrelated project to extract the metadata. It also suffered from not properly supporting overloaded methods.

To improve the situation, we should …

  • … create a Spring Modulith-native way of extracting Javadoc from the code base. Spring Boot uses an APT to extract Javadoc from configuration property fields. We should be able to do the same, but rather inspect all types and methods. The code creating the Application Module Canvas should be reviewed to make more use of that metadata.
  • … fold in the metadata-loading parts of Spring Auto RESTDocs to avoid the additional test scope dependency. As the project is not maintained anymore, it's safe to assume no further adjustments to their code base. We should officially deprecate the support in the form of a warning log if a Spring Auto RESTDocs configuration file is found.
@odrotbohm odrotbohm added in: documentation support Documentation generation type: enhancement Major enhanvements, new features labels Oct 3, 2024
@odrotbohm odrotbohm added this to the 1.3 RC1 milestone Oct 3, 2024
@odrotbohm odrotbohm self-assigned this Oct 3, 2024
@odrotbohm odrotbohm changed the title Support Spring-Modulith-only extraction of Javadoc into Application Module Canvases Support Spring-Modulith-native extraction of Javadoc into Application Module Canvases Oct 3, 2024
odrotbohm added a commit that referenced this issue Oct 4, 2024
…ion Module Canvases.

We now ship our own APT (included in the core starter) that automatically extracts the user code's Javadoc into a metadata file in generated-spring-modulith/javadoc.json. The documentation generation support picks up that file through SpringModulithDocumentationSource. Asciidoctor has been extended to make more use of the Javadoc where ever it renders a plain type.
odrotbohm added a commit that referenced this issue Oct 6, 2024
Fix invalid @see tag.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
in: documentation support Documentation generation type: enhancement Major enhanvements, new features
Projects
None yet
Development

No branches or pull requests

1 participant