Clarification PublisherService

@@ -4,26 +4,71 @@ import org.legrog.entities.Publisher;
 import org.legrog.entities.PublisherAction;
 import org.legrog.entities.PublisherVersion;
 
+import javax.validation.constraints.NotNull;
 import java.util.List;
 
 /*
-    Interface correspondant à la gestion des éditeurs et de leurs versions.
-    Contient des signatures méthodes d'ajout, de modification et de validation de version ainsi que de restitution.
+    Interface correspondant à la gestion des éditeurs, de leurs versions et des actions correspondantes.
+    Contient des signatures pour les méthodes d'ajout, de modification et de validation de version ainsi
+    que de restitution.
  */
 public interface PublisherService {
 
-    PublisherVersion addNewPublisher(PublisherVersion publisherVersion);
+    /*
+        @param PublisherVersion for creation of new Publisher ; has no publisher, author or date time
 
-    PublisherVersion addVersionToPublisher(Publisher publisher, PublisherVersion publisherVersion);
+        Creates Publisher, associates it with PublisherVersion and back.
+        PublisherVersion is completed with author and date time.
+        Both Publisher and PublisherVersion are persisted.
 
-    PublisherAction validatePublisherVersion(PublisherVersion publisherVersion);
+        @return updated PublisherVersion
+     */
+    PublisherVersion addNewPublisher(@NotNull PublisherVersion publisherVersion);
+
+    /*
+        @param Publisher has at least one version
+        @param PublisherVersion has no publisher, author or date time
+
+        Updates Publisher's versions, adding PublisherVersion. Reverse association is also done.
+        PublisherVersion is completed with author and date time.
+        Both Publisher and PublisherVersion are persisted.
+
+        @return updated PublisherVersion
+     */
+    PublisherVersion addVersionToPublisher(@NotNull Publisher publisher, @NotNull PublisherVersion publisherVersion);
+
+    /*
+        @param PublisherVersion
+
+        Sets PublisherVersion as its Publisher validated version.
+        Creates the PublisherAction for the validation.
+        Both Publisher and PublisherAction are persisted.
 
+        @return PublisherAction related to the validation
+     */
+    PublisherAction validatePublisherVersion(@NotNull PublisherVersion publisherVersion);
+
+    /* @return all persisted PublisherVersions */
     List<PublisherVersion> getAllPublisherVersions();
 
-    PublisherVersion getPublisherVersion(Integer publisherVersionId);
+    /*
+        @param publisherVersionId
+        @return PublisherVersion with id publisherVersionId
+    */
+    PublisherVersion getPublisherVersion(@NotNull Integer publisherVersionId);
 
-    PublisherAction getLastValidate(Publisher publisher);
+    /*
+        @param Publisher
+        @return PublisherAction for Publisher's last validation
+    */
+    PublisherAction getLastValidate(@NotNull Publisher publisher);
 
+    /* @return all persisted PublisherAction */
     List<PublisherAction> getAllPublisherActions();
-    List<PublisherAction> getAllPublisherVersionActions(PublisherVersion publisherVersion);
+
+    /*
+        @param PublisherVersion
+        @return all PublisherAction on that PublisherVersion
+    */
+    List<PublisherAction> getAllPublisherVersionActions(@NotNull PublisherVersion publisherVersion);
 }