Skip to content
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

Exclude generated outer classes from including into documentation #153

Open
alexander-yevsyukov opened this issue Aug 19, 2024 · 1 comment
Labels
documentation Improvements or additions to documentation

Comments

@alexander-yevsyukov
Copy link
Contributor

Currently, outer classes generated by Protobuf are included into Javadocs and KDocs. For example, in io.spine.protodata package we have AstProto, DeclarationsProto, FileProto, InsertionProto, and other classes suffixes with Proto for all Protobuf source code files. There's nothing useful for end users in these documents, they just add up noice by appearing in the list of useful items.

We need to exclude these classes from generated documentation in both Javadoc and KDoc.

One of the possible approaches would be to add @Internal annotation for the generated outer classes.
Alternatively, we can add a custom annotation similar to @suppress in KDoc and handle it.

@alexander-yevsyukov alexander-yevsyukov added the documentation Improvements or additions to documentation label Aug 19, 2024
@armiol
Copy link
Contributor

armiol commented Aug 19, 2024

If we go for the approach based on @Internal annotation, the repository dokka-tools should be brought to life first. Currently, it's a bit outdated.

Alternatively (and I would NOT go for it right now), there is a way to introduce a custom Javadoc tag, similar to KDoc's @hide. And create a Dokka plugin which would handle it, similar how it handles @hide for Android.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants