joffrey-bion
commented
6 years ago Interesting. I'm usually against systematic suffixes/prefixes in my own projects, because as you said they add noise, and not only to the doc but to the code itself, especially for -DTO. Usually, packages are sufficient to avoid having to use prefixes/suffixes. If the name of the type makes sense without the suffix from the documentation's point of view, then why not remove it from the code itself?
On the other hand, we could imagine situations where such a suffix is used for a reason and we dont want to remove it, like a custom map type ThingByEndpoint mapping Endpoints to things. I guess that is why I would rather not enable prefixes/suffixes removal by default.
Regarding the -Controller suffix, it is actually necessary to describe what the class is (BookController is not a book, it is a thing that manages requests regarding books, whereas BookDTO is in fact just a book, the fact that it is serialized and sent is independent from the fact that it is a description of a book).
In the case of the controller, simply removing the suffix is kinda confusing because we would be writing "Book" when talking about the "Book API". But here, replacing the -Controller suffix by API could indeed make sense and look nicer in the doc.
In any case, I like the idea to make post-processing of the data easier, even if, as you said, it is already doable using a custom controller to serve the Livedoc. For instance, we could provide a generic post-processor interface and a few built-in implementations like prefix/suffix removers for instance. By default, they would not be added, but the user could add them easily in Livedoc's configuration.
The goal would be to enable the user to customize Livedoc with an effort that is proportional to how much you change the default behaviour. Overriding names should not require a hundred annotations, nor should it require the user to visit the whole doc structure to update tiny bits.
ST-DDT
The java classes usually have suffixes based on their type.
These suffixes might be:
These suffixes don't add any value to the documentation (only noise) and thus are removed by me.
Currently you have to annotate all of those classes to omit this suffix. (Which adds noise to the source code)
Suggestion
Have a built in list of common suffixes that should be removed.
Alternative
Allow specifying a custom post processor, that can replace project specific suffixes. (This is already possible (but complex), if you just use a custom JsonLiveDocController, that cleans the result of the original one)