Today when we add descriptions to yang the description shows up in javadoc. This is a good thing but I think there is an aspect of javadoc which you cannot include in the yang documentation which is how to use the generated java interfaces/dtos.

Obviously we cannot add java documentation into yang but we do need to add sort sort of documentation augmentation to the yang inorder to provide a usable javadoc.