DS-3533 Adjust javadocs

dspace-server-webapp/src/main/java/org/dspace/app/rest/model/LinkRest.java

@@ -19,8 +19,7 @@ import org.dspace.app.rest.utils.Utils;
 import org.springframework.stereotype.Component;
 
 /**
- * Class or method-level annotation to control linking/embedding behavior when a {@link RestModel}
+ * Class or method-level annotation to provide information about linked/embedded subresources of a {@link RestModel}.
- * is wrapped as a {@link HALResource}
  *
  * @author Andrea Bollini (andrea.bollini at 4science.it)
  */

dspace-server-webapp/src/main/java/org/dspace/app/rest/projection/AbstractProjection.java

@@ -12,8 +12,9 @@ import org.dspace.app.rest.model.RestModel;
 import org.dspace.app.rest.model.hateoas.HALResource;
 
 /**
- * Abstract base class for projections. By default no transformation is done, optional embeds are not included,
+ * Abstract base class for projections.
- * and optional links are included.
+ *
+ * By default, this does no transformation, and allows linking but not embedding of all subresources.
  */
 public abstract class AbstractProjection implements Projection {
 

dspace-server-webapp/src/main/java/org/dspace/app/rest/projection/DefaultProjection.java

@@ -8,7 +8,9 @@
 package org.dspace.app.rest.projection;
 
 /**
- * The default projection, which has no effect.
+ * The default projection.
+ *
+ * This does no transformation, and allows linking but not embedding of all subresources.
  */
 public class DefaultProjection extends AbstractProjection {
 

dspace-server-webapp/src/main/java/org/dspace/app/rest/projection/FullProjection.java

@@ -11,6 +11,9 @@ import org.dspace.app.rest.model.LinkRest;
 import org.dspace.app.rest.model.hateoas.HALResource;
 import org.springframework.stereotype.Component;
 
+/**
+ * Catch-all projection that allows embedding of all subresources.
+ */
 @Component
 public class FullProjection extends AbstractProjection {
 

dspace-server-webapp/src/main/java/org/dspace/app/rest/projection/Projection.java

@@ -106,10 +106,13 @@ public interface Projection {
     <T extends HALResource> T transformResource(T halResource);
 
     /**
-     * Tells whether this projection permits the embedding of a particular optionally-embeddable related resource.
+     * Tells whether this projection permits the embedding of a particular embeddable subresource.
      *
      * This gives the projection an opportunity to opt in to to certain embeds, by returning {@code true}.
      *
+     * Note: If this method returns {@code true} for a given subresource,
+     * it will be automatically linked regardless of what {@link #allowLinking(HALResource, LinkRest)} returns.
+     *
      * @param halResource the resource from which the embed may or may not be made.
      * @param linkRest the LinkRest annotation through which the related resource was discovered on the rest object.
      * @return true if allowed, false otherwise.
@@ -117,10 +120,13 @@ public interface Projection {
     boolean allowEmbedding(HALResource halResource, LinkRest linkRest);
 
     /**
-     * Tells whether this projection permits the linking of a particular optionally-linkable related resource.
+     * Tells whether this projection permits the linking of a particular linkable subresource.
      *
      * This gives the projection an opportunity to opt in to to certain links, by returning {@code true}.
      *
+     * Note: If {@link #allowEmbedding(HALResource, LinkRest)} returns {@code true} for a given subresource,
+     * it will be automatically linked regardless of what this method returns.
+     *
      * @param halResource the resource from which the link may or may not be made.
      * @param linkRest the LinkRest annotation through which the related resource was discovered on the rest object.
      * @return true if allowed, false otherwise.