[LMS-2568] improve javadocs

SVN: 23166

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IDataSetType.java

@@ -22,6 +22,9 @@ package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 public interface IDataSetType extends IDataSetTypeImmutable
 {
 
+    /**
+     * Set to <code>true</code> if the type is a container type.
+     */
     public void setContainerType(boolean isContainerType);
 
     /**

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IDataSetTypeImmutable.java

@@ -17,11 +17,16 @@
 package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 
 /**
+ * Read-only interface to an data set type.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IDataSetTypeImmutable extends IEntityType
 {
 
+    /**
+     * Return <code>true</code> if the data set type is container type.
+     */
     public boolean isContainerType();
 
 }

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IExperimentTypeImmutable.java

@@ -17,6 +17,8 @@
 package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 
 /**
+ * Read-only interface to an existing experiment type.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IExperimentTypeImmutable extends IEntityType

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IFileFormatTypeImmutable.java

@@ -17,6 +17,8 @@
 package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 
 /**
+ * Read-only interface to an existing file format type.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IFileFormatTypeImmutable extends IAbstractType

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IMasterDataRegistrationTransaction.java

@@ -19,31 +19,111 @@ package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 import java.util.List;
 
 /**
+ * API for master data registration. Offers methods for creation and retrieval of openBIS types,
+ * property assignments, vocabularies etc.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IMasterDataRegistrationTransaction
 {
 
+    /**
+     * Create a new experiment type to register with the openBIS AS.
+     * 
+     * @param code the experiment type's code.
+     */
     IExperimentType createNewExperimentType(String code);
 
+    /**
+     * Get an experiment type from the openBIS AS. Returns null if the experiment type does not
+     * exist.
+     * 
+     * @return An experiment type or null
+     */
     IExperimentTypeImmutable getExperimentType(String code);
 
+    /**
+     * Return all experiment types existing in the openBIS AS.
+     */
+    List<IExperimentTypeImmutable> listExperimentTypes();
+
+    /**
+     * Create a new sample type to register with the openBIS AS.
+     * 
+     * @param code the sample type's code.
+     */
     ISampleType createNewSampleType(String code);
 
+    /**
+     * Get a sample type from the openBIS AS. Returns null if the sample type does not exist.
+     * 
+     * @return A sample type or null
+     */
     ISampleTypeImmutable getSampleType(String code);
 
+    /**
+     * Return all sample types existing in the openBIS AS.
+     */
+    List<ISampleTypeImmutable> listSampleTypes();
+
+    /**
+     * Create a new data set type to register with the openBIS AS.
+     * 
+     * @param code the data set type's code.
+     */
     IDataSetType createNewDataSetType(String code);
 
+    /**
+     * Get a data set type from the openBIS AS. Returns null if the data set type does not exist.
+     * 
+     * @return A data set type or null
+     */
     IDataSetTypeImmutable getDataSetType(String code);
 
+    /**
+     * Return all data set types existing in the openBIS AS.
+     */
+    List<IDataSetTypeImmutable> listDataSetTypes();
+
+    /**
+     * Create a new material type to register with the openBIS AS.
+     * 
+     * @param code the material type's code.
+     */
     IMaterialType createNewMaterialType(String code);
 
+    /**
+     * Get a material type from the openBIS AS. Returns null if the material type does not exist.
+     * 
+     * @return A material type or null
+     */
     IMaterialTypeImmutable getMaterialType(String code);
 
+    /**
+     * Return all material types existing in the openBIS AS.
+     */
+    List<IMaterialTypeImmutable> listMaterialTypes();
+
+    /**
+     * Create a new property type to register with the openBIS AS.
+     * 
+     * @param code the property type's code.
+     * @param dataType the data type of the property
+     */
     IPropertyType createNewPropertyType(String code, DataType dataType);
 
+    /**
+     * Get a property type from the openBIS AS. Returns null if the property type does not exist.
+     * 
+     * @return A property type or null
+     */
     IPropertyTypeImmutable getPropertyType(String code);
 
+    /**
+     * Return all property types existing in the openBIS AS.
+     */
+    List<IPropertyTypeImmutable> listPropertyTypes();
+
     /**
      * Assigns a property type to an entity type.
      * 
@@ -60,14 +140,51 @@ public interface IMasterDataRegistrationTransaction
      */
     List<IPropertyAssignmentImmutable> listPropertyAssignments();
 
-    IVocabularyTerm createNewVocabularyTerm(String code);
+    /**
+     * Create a new file format type to register with the openBIS AS.
+     * 
+     * @param code the file format type's code.
+     */
+    IFileFormatType createNewFileFormatType(String code);
+
+    /**
+     * Get a file format type from the openBIS AS. Returns null if the file format type does not
+     * exist.
+     * 
+     * @return A file format type or null
+     */
+    IFileFormatTypeImmutable getFileFormatType(String code);
 
+    /**
+     * Return all file format types existing in the openBIS AS.
+     */
+    List<IFileFormatTypeImmutable> listFileFormatTypes();
+
+    /**
+     * Create a new sample type to register with the openBIS AS.
+     * 
+     * @param code the sample type's code.
+     */
     IVocabulary createNewVocabulary(String code);
 
-    // Not yet implemented
-    // IVocabularyImmutable getVocabulary(String code);
+    /**
+     * Get a vocabulary from the openBIS AS. Returns null if the vocabulary does not exist.
+     * 
+     * @return A vocabulary or null
+     */
+    IVocabularyImmutable getVocabulary(String code);
+
+    /**
+     * Return all vocabularies existing in the openBIS AS.
+     */
+    List<IVocabularyImmutable> listVocabularies();
 
-    IFileFormatType createNewFileFormatType(String code);
+    /**
+     * Create a new vocabulary term. The resulting object can be added to a vocabulary via the
+     * {@link IVocabulary#addTerm(IVocabularyTerm)} method.
+     * 
+     * @param code the vocabulary term's code
+     */
+    IVocabularyTerm createNewVocabularyTerm(String code);
 
-    IFileFormatTypeImmutable getFileFormatType(String code);
 }

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IMaterialTypeImmutable.java

@@ -17,6 +17,8 @@
 package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 
 /**
+ * Read-only interface to an existing material type.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IMaterialTypeImmutable extends IEntityType

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IPropertyAssignment.java

@@ -21,8 +21,16 @@ package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
  */
 public interface IPropertyAssignment extends IPropertyAssignmentImmutable
 {
+
+    /**
+     * Set to <code>true</code> if the property is mandatory for the assigned entity type.
+     */
     void setMandatory(boolean mandatory);
 
+    /**
+     * Set the name of the form section. It will appear when editing objects of the specified entity
+     * in openBIS. Specifying a section name is optional.
+     */
     void setSection(String section);
 
     /**

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IPropertyAssignmentImmutable.java

@@ -17,20 +17,41 @@
 package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 
 /**
+ * Read-only interface to an existing property assignment.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IPropertyAssignmentImmutable
 {
-    EntityKind getEntityKind();
-
+    /**
+     * Return the code of the assigned entity type.
+     */
     String getEntityTypeCode();
 
+    /**
+     * Return the kind of the assigned entity type.
+     */
+    EntityKind getEntityKind();
+
+    /**
+     * Return the code of the assigned property type.
+     */
     String getPropertyTypeCode();
 
+    /**
+     * Return <code>true</code> if the property is mandatory for the assigned entity type.
+     */
     boolean isMandatory();
 
+    /**
+     * Return the name of the form section.
+     */
     String getSection();
 
+    /**
+     * Return the position at which the property will be rendered when editing/registering objects
+     * of the specified entity type.
+     */
     Long getPositionInForms();
 
 }

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IPropertyTypeImmutable.java

@@ -17,6 +17,8 @@
 package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 
 /**
+ * Read-only interface to an existing property type.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IPropertyTypeImmutable extends IAbstractType

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/ISampleTypeImmutable.java

@@ -17,6 +17,8 @@
 package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 
 /**
+ * Read-only interface to an existing sample type.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface ISampleTypeImmutable extends IEntityType

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IVocabulary.java

@@ -27,8 +27,14 @@ public interface IVocabulary extends IVocabularyImmutable
      */
     public void setDescription(String description);
 
+    /**
+     * Set to <code>true</code> if the vocabulary is managed internally in openBIS.
+     */
     void setManagedInternally(boolean isManagedInternally);
 
+    /**
+     * Set to <code>true</code> if the vocabulary is in the internal openBIS namespace.
+     */
     void setInternalNamespace(boolean isInternalNamespace);
 
     void setChosenFromList(boolean isChosenFromList);

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IVocabularyImmutable.java

@@ -19,6 +19,8 @@ package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 import java.util.List;
 
 /**
+ * Read-only interface to a vocabulary.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IVocabularyImmutable
@@ -34,8 +36,14 @@ public interface IVocabularyImmutable
      */
     public String getDescription();
 
+    /**
+     * Return <code>true</code> if the vocabulary is managed internally in openBIS.
+     */
     boolean isManagedInternally();
 
+    /**
+     * Return <code>true</code> if the vocabulary is in the internal openBIS namespace.
+     */
     boolean isInternalNamespace();
 
     boolean isChosenFromList();
@@ -46,6 +54,9 @@ public interface IVocabularyImmutable
      */
     String getUrlTemplate();
 
+    /**
+     * Return a list with all terms within the vocabulary.
+     */
     List<IVocabularyTermImmutable> getTerms();
 
 }

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IVocabularyTerm.java

@@ -21,11 +21,23 @@ package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
  */
 public interface IVocabularyTerm extends IVocabularyTermImmutable
 {
+    /**
+     * Set the description of the vocabulary term.
+     */
     void setDescription(String description);
 
+    /**
+     * Set the label of the vocabulary term.
+     */
     void setLabel(String label);
 
+    /**
+     * Set a URL where containing additional information for the term.
+     */
     void setUrl(String url);
 
+    /**
+     * Set position of the term in the context of its vocabulary.
+     */
     void setOrdinal(Long ordinal);
 }

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/jython/api/v1/IVocabularyTermImmutable.java

@@ -17,18 +17,35 @@
 package ch.systemsx.cisd.openbis.generic.server.jython.api.v1;
 
 /**
+ * Read-only interface to an existing vocabulary term.
+ * 
  * @author Kaloyan Enimanev
  */
 public interface IVocabularyTermImmutable
 {
+    /**
+     * Return the term's code.
+     */
     String getCode();
 
+    /**
+     * Return the term's description.
+     */
     String getDescription();
 
+    /**
+     * Return the term's label.
+     */
     String getLabel();
 
+    /**
+     * Return an associated URL specifying additional information for the vocabulary term.
+     */
     String getUrl();
 
+    /**
+     * Return the position of the term in the context of a vocabulary.
+     */
     Long getOrdinal();
 
 }