From 66b77c3e5a49684d98c8a470fc11f88e90d94b82 Mon Sep 17 00:00:00 2001
From: "m.geoffroy" <m.geoffroy@localhost>
Date: Thu, 5 Jun 2008 14:57:05 +0000
Subject: [PATCH]

---
 .../cdm/model/name/TaxonNameBase.java         | 94 ++++++++++++++++---
 1 file changed, 81 insertions(+), 13 deletions(-)

diff --git a/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/TaxonNameBase.java b/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/TaxonNameBase.java
index 14de364e96..b1bf3de05e 100644
--- a/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/TaxonNameBase.java
+++ b/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/TaxonNameBase.java
@@ -515,6 +515,23 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 		this.nameTypeDesignations = nameTypeDesignations;
 	}
 	
+	/** 
+	 * Returns the set of {@link SpecimenTypeDesignation specimen type designations} assigned
+	 * indirectly to this taxon name through its {@link HomotypicalGroup homotypical group}.
+	 * The rank of this taxon name is generally "species" or below.
+	 * The specimen type designations include all the specimens on which
+	 * the typification of this name is based (and which are common to all
+	 * taxon names belonging to the homotypical group) and eventually
+	 * the status of these designations.
+	 *
+	 * @see     SpecimenTypeDesignation
+	 * @see     NameTypeDesignation
+	 */
+	@Transient
+	public Set<SpecimenTypeDesignation> getSpecimenTypeDesignations() {
+		return this.getHomotypicalGroup().getTypeDesignations();
+	}
+	
 	/** 
 	 * Creates and adds a new {@link NameTypeDesignation name type designation}
 	 * to this taxon name's set of name type designations.
@@ -557,6 +574,7 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 	 * @see     		  		#removeTypeDesignation(SpecimenTypeDesignation)
 	 */
 	public void removeTypeDesignation(NameTypeDesignation typeDesignation) {
+		logger.warn("not yet fully implemented: nullify the name type designation itself?");
 		this.nameTypeDesignations.remove(typeDesignation);
 	}
 	/** 
@@ -569,13 +587,14 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 	 * @see     		  		#removeTypeDesignation(NameTypeDesignation)
 	 */
 	public void removeTypeDesignation(SpecimenTypeDesignation typeDesignation) {
+		logger.warn("not yet fully implemented: nullify the specimen type designation itself?");
 		this.homotypicalGroup.removeTypeDesignation(typeDesignation);
 	}
 
 	/** 
 	 * Returns the {@link HomotypicalGroup homotypical group} to which
-	 * this taxon name belongs. A homotypical group represents all names that
-	 * share the same type specimens.
+	 * this taxon name belongs. A homotypical group represents all taxon names
+	 * that share the same type specimens.
 	 *
 	 * @see 	HomotypicalGroup
 	 */
@@ -591,10 +610,20 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 
 	@Transient
 	public StrictReferenceBase getCitation(){
+		//TODO What is the purpose of this method differing from the getNomenclaturalReference method? 
 		logger.warn("getCitation not yet implemented");
 		return null;
 	}
 
+	/** 
+	 * Returns the complete string containing the
+	 * {@link reference.INomenclaturalReference#getNomenclaturalCitation() nomenclatural reference citation}
+	 * (including {@link #getNomenclaturalMicroReference() details}) assigned to this taxon name.
+	 * 
+	 * @see	reference.INomenclaturalReference#getNomenclaturalCitation()
+	 * @see	#getNomenclaturalReference()
+	 * @see	#getNomenclaturalMicroReference()
+	 */
 	@Transient
 	public String getCitationString(){
 		logger.warn("getCitationString not yet implemented");
@@ -608,8 +637,11 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 	}
 
 	/**
-	 * returns year of according nomenclatural reference, null if nomenclatural
-	 * reference does not exist
+	 * Returns the string containing the publication date (generally only year)
+	 * of the nomenclatural reference, null if there is no nomenclatural
+	 * reference.
+	 * 
+	 * @see	reference.INomenclaturalReference#getYear()
 	 */
 	@Transient
 	public String getReferenceYear(){
@@ -620,10 +652,24 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 		}
 	}
 
+	/** 
+	 * Returns the set of {@link taxon.TaxonBase taxon bases} that refer to this taxon name.
+	 * In this context a taxon base means the use of a taxon name by a reference
+	 * either as a taxon ("accepted/correct" name) or as a (junior) synonym.
+	 * A taxon name can be used by several distinct references but only once
+	 * within a taxonomic treatment (identified by one reference).
+	 *
+	 * @see  taxon.TaxonBase
+	 * @see	#getTaxa()
+	 * @see	#getSynonyms()
+	 */
 	@OneToMany(mappedBy="name", fetch= FetchType.EAGER)
 	public Set<TaxonBase> getTaxonBases() {
 		return this.taxonBases;
 	}
+	/** 
+	 * @see     #getTaxonBases()
+	 */
 	protected void setTaxonBases(Set<TaxonBase> taxonBases) {
 		if (taxonBases == null){
 			taxonBases = new HashSet<TaxonBase>();
@@ -631,6 +677,13 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 			this.taxonBases = taxonBases;
 		}
 	}
+	/** 
+	 * Adds a new {@link taxon.TaxonBase taxon base}
+	 * to the set of taxon bases using this taxon name.
+	 *
+	 * @param  taxonBase  the taxon base to be added
+	 * @see 			  #getTaxonBases()
+	 */
 	//TODO protected
 	public void addTaxonBase(TaxonBase taxonBase){
 		taxonBases.add(taxonBase);
@@ -657,8 +710,13 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 	
 	
 	/**
-	 * Return a set of taxa that use this name.
-	 * @return Set<Taxon> The set of taxa this TaxonName belongs to
+	 * Returns the set of {@link taxon.Taxon taxa} ("accepted/correct" names according to any
+	 * reference) that are based on this taxon name. This set is a subset of
+	 * the set returned by getTaxonBases(). 
+	 * 
+	 * @see	taxon.Taxon
+	 * @see	#getTaxonBases()
+	 * @see	#getSynonyms()
 	 */
 	@Transient
 	public Set<Taxon> getTaxa(){
@@ -672,8 +730,13 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 	}
 	
 	/**
-	 * Return a set of synonyms that use this name
-	 * @return The set of synonyms this TaxonName belongs to
+	 * Returns the set of {@link taxon.Synonym (junior) synonyms} (according to any
+	 * reference) that are based on this taxon name. This set is a subset of
+	 * the set returned by getTaxonBases(). 
+	 * 
+	 * @see	taxon.Synonym
+	 * @see	#getTaxonBases()
+	 * @see	#getTaxa()
 	 */
 	@Transient
 	public Set<Synonym> getSynonyms() {
@@ -686,12 +749,17 @@ public abstract class TaxonNameBase<T extends TaxonNameBase, S extends INameCach
 		return result;
 	}
 	
-	@Transient
-	public Set<SpecimenTypeDesignation> getSpecimenTypeDesignations() {
-		return this.getHomotypicalGroup().getTypeDesignations();
-	}
-	
 // ***********
+	/**
+	 * Returns the boolean value indicating whether a given taxon name belongs
+	 * to the same {@link HomotypicalGroup homotypical group} as this taxon name (true)
+	 * or not (false). Returns "true" only if the homotypical groups of both
+	 * taxon names exist and if they are identical. 
+	 *
+	 * @param	homoTypicName  the taxon name the homotypical group of which is to be checked
+	 * @return  			   the boolean value of the check
+	 * @see     			   HomotypicalGroup
+	 */
 	public boolean isHomotypic(TaxonNameBase homoTypicName) {
 		if (homoTypicName == null) {
 			return false;
-- 
2.34.1