Document YangModuleInfo(Provider)

New javadoc is rather more noisy about missing documentation. Improve
the situation for module info and its ServiceLoader provider.

JIRA: MDSAL-755
Change-Id: I9d008a737b4db992664b24babfe206219b975e90
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
(cherry picked from commit 49c4ce7520f9870ad0aecbafd73aa94e4521af3f)

diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/YangModuleInfoTemplate.xtend b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/YangModuleInfoTemplate.xtend
index 4ee07e08e4409a34ea901082a1843707518b28d2..3efa63801350fb6f9d5442352b98a42e0be77f8f 100644 (file)
--- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/YangModuleInfoTemplate.xtend
+++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/YangModuleInfoTemplate.xtend
@@ -89,6 +89,9 @@ class YangModuleInfoTemplate {
         collectSubmodules(submodules, module)
 
         val body = '''
+            /**
+             * The {@link ResourceYangModuleInfo} for {@code «module.name»} module.
+             */
             @«JavaFileTemplate.GENERATED»("mdsal-binding-generator")
             public final class «MODULE_INFO_CLASS_NAME» extends ResourceYangModuleInfo {
                 «val rev = module.revision»
@@ -97,10 +100,24 @@ class YangModuleInfoTemplate {
 
                 private final @NonNull ImmutableSet<YangModuleInfo> importedModules;
 
+                /**
+                 * Return the singleton instance of this class.
+                 *
+                 * @return The singleton instance
+                 */
                 public static @NonNull YangModuleInfo getInstance() {
                     return INSTANCE;
                 }
 
+                /**
+                 * Create an interned {@link QName} with specified {@code localName} and namespace/revision of this
+                 * module.
+                 *
+                 * @param localName local name
+                 * @return A QName
+                 * @throws NullPointerException if {@code localName} is null
+                 * @throws IllegalArgumentException if localName is not a valid YANG identifier
+                 */
                 public static @NonNull QName «MODULE_INFO_QNAMEOF_METHOD_NAME»(final String localName) {
                     return QName.create(NAME, localName).intern();
                 }
@@ -121,10 +138,23 @@ class YangModuleInfoTemplate {
         package «packageName»;
 
         import java.lang.Override;
+        import java.util.ServiceLoader;
         import org.opendaylight.yangtools.yang.binding.YangModelBindingProvider;
         import org.opendaylight.yangtools.yang.binding.YangModuleInfo;
 
+        /**
+         * The {@link YangModelBindingProvider} for {@code «module.name»} module. This class should not be used
+         * directly, but rather through {@link ServiceLoader}.
+         */
+        @«JavaFileTemplate.GENERATED»("mdsal-binding-generator")
         public final class «MODEL_BINDING_PROVIDER_CLASS_NAME» implements YangModelBindingProvider {
+            /**
+             * Construct a new provider.
+             */
+            public «MODEL_BINDING_PROVIDER_CLASS_NAME»() {
+                // No-op
+            }
+
             @Override
             public YangModuleInfo getModuleInfo() {
                 return «MODULE_INFO_CLASS_NAME».getInstance();