Che: Add Javadoc for DTO

[slemeur]

Our DTO can be used by contributors and are not documented.

Example:
https://github.com/eclipse/che/blob/5.0.0-Mx/wsmaster/che-core-api-machine-shared/src/main/java/org/eclipse/che/api/machine/shared/dto/MachineConfigDto.java

Having javadoc will be helpful to better understand the model and get documentation as you code.

[tolusha]

@slemeur We should document model not DTO

[slemeur]

Are DTO not used in code of plugins?

Model is internal of the system. Someone who is using the DTO should not have to explore the model to understand what the attributes, methods are.

[slemeur]

IDEs are handling the DTO documentation with the @override annotation.

But it does not mean that the DTO have a javadoc. There are many situations where the DTO documentation could be useful.

Swagger also display our DTO objects:

It is probably a duplicate effort of work (to document booth model + DTO classes), but it would help certain community contributors and plugin developers.

[garagatyi]

It is real pain to support the same javadocs for several classes, that's why it is virtually impossible to make javadocs of DTO up to date.
BTW Swagger uses DTOs but doesn't respect javadocs.

[gazarenkov]

Model should be documented, not DTO,
DTO is for data transport as it stated from the name, it is just implementation details.

Strongly -1 of duplicating javadocs, it would mean we will have it nowhere

[skabashnyuk]

@slemeur are you keep interesting on this issue?

[skabashnyuk]

won't fix