From: <th...@us...> - 2008-10-02 01:52:50
|
Revision: 7872 http://pcgen.svn.sourceforge.net/pcgen/?rev=7872&view=rev Author: thpr Date: 2008-10-02 01:52:47 +0000 (Thu, 02 Oct 2008) Log Message: ----------- doc Modified Paths: -------------- Trunk/pcgen/code/src/java/pcgen/cdom/formula/FixedSizeFormula.java Trunk/pcgen/code/src/java/pcgen/cdom/list/CompanionList.java Trunk/pcgen/code/src/java/pcgen/cdom/reference/AbstractReferenceManufacturer.java Trunk/pcgen/code/src/java/pcgen/cdom/reference/CategorizedReferenceManufacturer.java Trunk/pcgen/code/src/java/pcgen/cdom/reference/ReferenceManufacturer.java Trunk/pcgen/code/src/java/pcgen/cdom/reference/ReferenceUtilities.java Modified: Trunk/pcgen/code/src/java/pcgen/cdom/formula/FixedSizeFormula.java =================================================================== --- Trunk/pcgen/code/src/java/pcgen/cdom/formula/FixedSizeFormula.java 2008-10-02 01:21:59 UTC (rev 7871) +++ Trunk/pcgen/code/src/java/pcgen/cdom/formula/FixedSizeFormula.java 2008-10-02 01:52:47 UTC (rev 7872) @@ -96,9 +96,10 @@ /** * Resolves to the identifying value of the SizeAdjustment provided during - * construction of the FixedSizeFormula. + * construction of the FixedSizeFormula. This is resolved in context to the + * given PlayerCharacter and Source identifier. * - * @return the identifying value of the SizeAdjustment this FixedSizeFormula + * @return The identifying value of the SizeAdjustment this FixedSizeFormula * represents. */ public Integer resolve(PlayerCharacter pc, String source) @@ -106,12 +107,29 @@ return Globals.sizeInt(size.getAbbreviation()); } + /** + * Resolves to the identifying value of the SizeAdjustment provided during + * construction of the FixedSizeFormula. This is resolved in context to both + * a piece of Equipment, the given PlayerCharacter, and the given Source + * identifier. + * + * @return The identifying value of the SizeAdjustment this FixedSizeFormula + * represents. + */ public Number resolve(Equipment equipment, boolean primary, PlayerCharacter apc, String string) { return Globals.sizeInt(size.getAbbreviation()); } + /** + * Returns true if this Formula is static (will always return the same + * value). As a FixedSizeFormula will always return the same value except in + * circumvention of a key assumption (a consistent, ordered set of + * SizeAdjustment objects in a given GameMode), this will return true. + * + * @return true + */ public boolean isStatic() { return true; Modified: Trunk/pcgen/code/src/java/pcgen/cdom/list/CompanionList.java =================================================================== --- Trunk/pcgen/code/src/java/pcgen/cdom/list/CompanionList.java 2008-10-02 01:21:59 UTC (rev 7871) +++ Trunk/pcgen/code/src/java/pcgen/cdom/list/CompanionList.java 2008-10-02 01:52:47 UTC (rev 7872) @@ -20,9 +20,18 @@ import pcgen.cdom.base.CDOMListObject; import pcgen.core.Race; +/** + * CompanionList is a CDOMListObject designed to reference a List of Race + * objects available as companions to a PlayerCharacter objects. + */ public class CompanionList extends CDOMListObject<Race> { + /** + * Returns the Race Class object (Race.class) + * + * @return the Race Class object (Race.class) + */ public Class<Race> getListClass() { return Race.class; Modified: Trunk/pcgen/code/src/java/pcgen/cdom/reference/AbstractReferenceManufacturer.java =================================================================== --- Trunk/pcgen/code/src/java/pcgen/cdom/reference/AbstractReferenceManufacturer.java 2008-10-02 01:21:59 UTC (rev 7871) +++ Trunk/pcgen/code/src/java/pcgen/cdom/reference/AbstractReferenceManufacturer.java 2008-10-02 01:52:47 UTC (rev 7872) @@ -299,14 +299,13 @@ T activeObj = active.get(me1.getKey()); if (activeObj == null) { - String reduced = - AbilityUtilities.getUndecoratedName(me1.getKey(), - throwaway); + String reduced = AbilityUtilities.getUndecoratedName(me1 + .getKey(), throwaway); activeObj = active.get(reduced); if (activeObj == null) { Logging.errorPrint("Unable to Resolve: " + refClass + " " - + me1.getKey()); + + me1.getKey()); } else { @@ -903,6 +902,20 @@ return referenced.values(); } + /** + * Injects all objects from the given ReferenceManufacturer into this + * AbstractReferenceManufacturer. Effectively this is a bulk addObject for + * all of the objects contained in the given ReferenceManufacturer. + * + * Note that this imports only the objects, and NOT references. This + * AbstractReferenceManufacturer does inherit any deferred objects + * (triggered through constructIfNecessary) from the given + * ReferenceManufacturer. + * + * @param arm + * The ReferenceManufacturer from which the objects should be + * imported into this AbstractReferenceManufacturer + */ protected void injectConstructed(ReferenceManufacturer<T, ?> arm) { for (Map.Entry<String, T> me : active.entrySet()) @@ -922,7 +935,35 @@ } } - + /** + * Triggers immediate construction of the object with the given identifier + * if it does not exist. This is an alternative to constructIfNecessary that + * should be used sparingly (generally direct access like this is higher + * risk, but necessary in some cases) + * + * Note that use of this method is inherently risky when taken in context to + * .MOD and .COPY. Changes to keys may change the object to which an + * identifier refers. Therefore, any resolution that should take place at + * runtime should use getReference and resovle the reference. + * + * The object will be constructed only if no object with the matching + * identifier has been constructed or imported into this + * ReferenceManufacturer. If the object has already been constructed, then + * the previously constructed object is returned. + * + * This method is effectively a convenience method that wraps + * containsObject, getObject, and constructObject into a single method call + * (and avoids the contains-triggered branch) + * + * @param name + * The identifier of the CDOMObject to be built (if otherwise not + * constructed or imported into this + * AbstractReferenceManufacturer), or if an object with that + * identifier already exists, the identifier of the object to be + * returned. + * @return The previously existing or new CDOMObject with the given + * identifier. + */ public T constructNowIfNecessary(String name) { T obj = active.get(name); Modified: Trunk/pcgen/code/src/java/pcgen/cdom/reference/CategorizedReferenceManufacturer.java =================================================================== --- Trunk/pcgen/code/src/java/pcgen/cdom/reference/CategorizedReferenceManufacturer.java 2008-10-02 01:21:59 UTC (rev 7871) +++ Trunk/pcgen/code/src/java/pcgen/cdom/reference/CategorizedReferenceManufacturer.java 2008-10-02 01:52:47 UTC (rev 7872) @@ -188,9 +188,15 @@ return obj; } + /** + * Returns a String representation of this CategorizedReferenceManufacturer + * + * @see java.lang.Object#toString() + */ @Override public String toString() { - return this.getClass().getName() + " [" + getReferenceClass() + " " + category + "]"; + return this.getClass().getName() + " [" + getReferenceClass() + " " + + category + "]"; } } \ No newline at end of file Modified: Trunk/pcgen/code/src/java/pcgen/cdom/reference/ReferenceManufacturer.java =================================================================== --- Trunk/pcgen/code/src/java/pcgen/cdom/reference/ReferenceManufacturer.java 2008-10-02 01:21:59 UTC (rev 7871) +++ Trunk/pcgen/code/src/java/pcgen/cdom/reference/ReferenceManufacturer.java 2008-10-02 01:52:47 UTC (rev 7872) @@ -271,5 +271,33 @@ */ public boolean validate(); + /** + * Triggers immediate construction of the object with the given identifier + * if it does not exist. This is an alternative to constructIfNecessary that + * should be used sparingly (generally direct access like this is higher + * risk, but necessary in some cases) + * + * Note that use of this method is inherently risky when taken in context to + * .MOD and .COPY. Changes to keys may change the object to which an + * identifier refers. Therefore, any resolution that should take place at + * runtime should use getReference and resovle the reference. + * + * The object will be constructed only if no object with the matching + * identifier has been constructed or imported into this + * ReferenceManufacturer. If the object has already been constructed, then + * the previously constructed object is returned. + * + * This method is effectively a convenience method that wraps + * containsObject, getObject, and constructObject into a single method call + * (and avoids the contains-triggered branch) + * + * @param name + * The identifier of the CDOMObject to be built (if otherwise not + * constructed or imported into this ReferenceManufacturer), or + * if an object with that identifier already exists, the + * identifier of the object to be returned. + * @return The previously existing or new CDOMObject with the given + * identifier. + */ public T constructNowIfNecessary(String name); } Modified: Trunk/pcgen/code/src/java/pcgen/cdom/reference/ReferenceUtilities.java =================================================================== --- Trunk/pcgen/code/src/java/pcgen/cdom/reference/ReferenceUtilities.java 2008-10-02 01:21:59 UTC (rev 7871) +++ Trunk/pcgen/code/src/java/pcgen/cdom/reference/ReferenceUtilities.java 2008-10-02 01:52:47 UTC (rev 7872) @@ -34,11 +34,18 @@ public final class ReferenceUtilities { + /** + * A COLLATOR used to sort Strings in a locale-aware method. + */ private final static Collator COLLATOR = Collator.getInstance(); + /** + * A Comparator to consistently sort CDOMReference objects. This is done + * using the ReferenceUtilities.compareRefs method. + */ public static final Comparator<CDOMReference<?>> REFERENCE_SORTER = new Comparator<CDOMReference<?>>() { - + public int compare(CDOMReference<?> arg0, CDOMReference<?> arg1) { return compareRefs(arg0, arg1); @@ -135,6 +142,29 @@ return StringUtil.join(resultSet, separator); } + /** + * Compares two CDOMReference objects to establish order. The primary + * purpose of this is to establish a consistent order across differnet + * hashing/ordering algorithms of various lists/sets that may contain + * CDOMReference objects. + * + * This method is compatible with (although not strictly adherent to the + * consistent-with-equals conditions of) the Comparable interface, in that + * it returns 0 if the CDOMReference objects are equal (at least in name, + * may not be consistent-with-equals), less than zero if the first given + * CDOMReference should be sorted before the second, and greater than zero + * if the first given CDOMReference should be sorted after the second. + * + * @param arg0 + * The first CDOMReference to be compared + * @param arg1 + * The second CDOMReference to be compared + * @return 0 if the CDOMReference objects are equal (at least in name, may + * not be consistent-with-equals), less than zero if the first given + * CDOMReference should be sorted before the second, and greater + * than zero if the first given CDOMReference should be sorted after + * the second. + */ public static int compareRefs(CDOMReference<?> arg0, CDOMReference<?> arg1) { if (arg0 instanceof CDOMSingleRef) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |