Definitions description based on Scaladoc about play-swagger

[Javakky-pxv]

@kailuowang
Please, advise.
It's a feature I'd like to have, but I'm wondering if it's a good idea to encourage users to install another compiler plugin.
Have you considered this feature in the past? And do you prefer this policy?

[kailuowang]

@kailuowang Please, advise. It's a feature I'd like to have, but I'm wondering if it's a good idea to encourage users to install another compiler plugin. Have you considered this feature in the past? And do you prefer this policy?

We thought about this. I don't feel super enthusiastic about this feature. It could be more convenient. But it also makes it necessary for the user to be very careful writing scaladoc comments in their code because it's automatically exposed to the API doc which is open.
Usually scaladoc is for internal dev consumption only, while open API doc has a more open access.
Play-swagger generates docs with information already available to the API consumer, i.e. field name and types. Scaladoc, on the other hand, is never available to API consumers.
I think fundamentally, scaladoc and swagger API specification are two different docs that serve different purposes and audiences. There are some overlaps and duplications, but using the same text for both might be risky.
That being said, If this can be an opt-in feature, I think some users can benefit from it as long as they understand the caveats.