Add missing javadocs

dspace-api/src/main/java/org/dspace/content/authority/Choice.java

@@ -34,7 +34,10 @@ public class Choice {
     public String value = null;
 
     /**
-     * A boolean representing if choice entry value can selected
+     * A boolean representing if choice entry value can selected (usually true).
+     * Hierarchical authority can flag some choice as not selectable to force the
+     * use to choice a more detailed terms in the tree, such a leaf or a deeper
+     * branch
      */
     public boolean selectable = true;
 

dspace-api/src/main/java/org/dspace/content/authority/ChoiceAuthority.java

@@ -88,18 +88,45 @@ default String getValue(String key, String locale) {
         return getLabel(key, locale);
     }
 
+    /**
+     * Get a map of additional information related to the specified key in the
+     * authority.
+     * 
+     * @param key    the key of the entry
+     * @param locale explicit localization key if available, or null
+     * @return a map of additional information related to the key
+     */
     default Map<String, String> getExtra(String key, String locale) {
         return new HashMap<String, String>();
     }
 
+    /**
+     * Return true for hierarchical authorities
+     * 
+     * @return <code>true</code> if hierarchical, default <code>false</code>
+     */
     default boolean isHierarchical() {
         return false;
     }
 
+    /**
+     * Scrollable authorities allows the scroll of the entries without applying
+     * filter/query to the
+     * {@link #getMatches(String, String, Collection, int, int, String)}
+     * 
+     * @return <code>true</code> if scrollable, default <code>false</code>
+     */
     default boolean isScrollable() {
         return false;
     }
 
+    /**
+     * Hierarchical authority can provide an hint for the UI about how many levels
+     * preload to improve the UX. It provides a valid default for hierarchical
+     * authorities
+     * 
+     * @return <code>0</code> if hierarchical, null otherwise
+     */
     default Integer getPreloadLevel() {
         return isHierarchical() ? 0 : null;
     }

dspace-api/src/main/java/org/dspace/content/authority/HierarchicalAuthority.java

@@ -70,8 +70,13 @@ public interface HierarchicalAuthority extends ChoiceAuthority {
      */
     public Choice getParentChoice(String authorityName, String vocabularyId, String locale);
 
+    /**
+     * Provides an hint for the UI to preload some levels to improve the UX. It
+     * usually mean that these preloaded level will be shown expanded by default
+     */
     public Integer getPreloadLevel();
 
+    @Override
     default boolean isHierarchical() {
         return true;
     }

dspace-api/src/main/java/org/dspace/content/authority/service/ChoiceAuthorityService.java

@@ -208,7 +208,9 @@ public Choices getBestMatch(String fieldKey, String query, Collection collection
     public Choices getTopChoices(String authorityName, int start, int limit, String locale);
 
     /**
-     *
+     * Return the direct parent of an entry identified by its id in an hierarchical
+     * authority.
+     * 
      * @param authorityName authority name
      * @param vocabularyId  child id
      * @param locale        explicit localization key if available, or null

dspace-server-webapp/src/main/java/org/dspace/app/rest/utils/AuthorityUtils.java

@@ -76,6 +76,18 @@ public VocabularyEntryDetailsRest convertEntryDetails(Choice choice, String auth
         return entry;
     }
 
+    /**
+     * This utility method is currently a workaround to enrich the REST object with
+     * information from the parent vocabulary that is not referenced by the Choice
+     * model
+     * 
+     * @param choice         the dspace-api choice to expose as vocabulary entry
+     * @param authorityName  the name of the vocabulary
+     * @param storeAuthority <code>true</code> if the entry id should be exposed as
+     *                       an authority for storing it in the metadatavalue
+     * @param projection     the rest projection to apply
+     * @return the vocabulary entry rest reppresentation of the provided choice
+     */
     public VocabularyEntryRest convertEntry(Choice choice, String authorityName, boolean storeAuthority,
             Projection projection) {
         if (choice == null) {