ScaCap
SectionBuilder always generates method-path and description sections
The SectionBuilder always generates method-path and description sections regardless of the given snippet names. See for example the following code snippet:
...
AutoDocumentation.sectionBuilder()
.snippetNames()
.skipEmpty(true)
.build()
...
Expected is a more or less empty auto-section.adoc file, but the actual content is
[[resources-...]]
=== A title
include::auto-method-path.adoc[]
include::auto-description.adoc[]
Ah, I see, it is in the template. Nevertheless the issue remains: One cannot not include method-path and description.
This is because there always is a method-path and description for any existing endpoint. You somehow want the entire section to disappear, which doesn't make sense. Then you can skip the documentation for it in the code, or not include it in your index asciidoc.
Hi. Thanks for the answer. .snippetNames() was just an example for the both method-path and description are always generated. Of course an empty section makes no sense.
However there might be reasons why you do not want the description or method-path to appear in the documentation but write a hard typed description yourself. For instance, we typically have a CrudControllerBase super class for all CRUD-like REST controllers. The description is taken from the (generically phrased) JavaDocs of this super class unless it is overridden by a specific REST controller. So you get a description like "Retrieves a list of entities of type {@code T}" instead of "Retrieves a list of users". Needless to say, this sounds terrible.
As I understand it you would like to override these sections with custom text in asciidoc (or some configuration). But if you say that this CrudControllerBase is overridden with specific subclasses, I take that you could just write this text into the JavaDoc of the subclass itself. I guess the text needs to be somewhere and to me it seems it's better off inside the class and JavaDoc than doing it externally in some config or asciidoc. Because then you introduce a "detachment" of the code and documentation, which we try to void as much as possible. Is there a reason you don't want to do it?
I fully agree that the text is best written as JavaDoc. Yet I am not completely sure, that it is the right way to overrides methods (in the REST controller subclasses in our case) with the sole purpose of providing JavaDocs. What is your opinion about that?
Anyway, I think if you give the developers the opportunity to customize the section – what you do and which is great – then why don't you give them full control? Passing SnippetRegistry.AUTO_METHOD_PATH and SnippetRegistry.AUTO_DESCRIPTION is no pain when you use the SectionBuilder anyway.
Can you please reopen this issue? Maybe some others of your team or the community want to join this discussion.
I get that overriding a method just to supply JavaDoc seems a bit weird, but that's what you/anyone needs to do if you want to customise a JavaDoc for sucblass (not only for targeting REST API docs, but code docs for internal devs as well).
So one thing I want to point out is that the phrase "Retrieves a list of entities of type {@code T}" is probably meaningless, since the internal developer knows what she is dealing with and API documentation reader is also aware what context is being described based on the title and path (e.g. most likely seeing path GET /users). So imho the whole "of type {@code T}" could be just removed, problem solved.
If you want to get better customisation feel free to bring up a PR.