DDSJAVA — Missing -behavioural- descriptions of the interface

Some parts of the interface (javadoc) are poorly documented especially with respect to behaviour. This Java documentation will be the key documentation for the new DDS application programmers. It may be trivial or implicit for the ones writing the standard but it will not be for the application programmers which are not familiar with the existing DDS standard will use it

For example have a look at the method createDataWriter(Topic<TYPE> topic) on the Publisher interface. What will happen if the middleware cannot create the datawriter. Will an unchecked exception be thrown or is a null value returned or even worse the datawriter is simply returned and will fail when the first write action is performed?

I now that the existing OpenSplice DDS implementation will return null when the middleware is not able to create the datawriter but it would be nice that applications are not only portable from interface compliance aspect but also from behavioural aspect! (and that application programmers are aware of it)

Merge the descriptions of classes and operations from the DDS specification into the appropriate JavaDoc comments. This PSM does not introduce new concepts, so no merge is necessary in that case. DDS-XTypes is in finalization, so its contents are not yet fixed. Therefore, to avoid the possibility of errors and inconsistencies, we should put it aside for now.