Updates during team code review.

tjnelsonfs · tjnelsonfs · commit 298607342db7 · 2025-02-25T11:44:17.000-07:00
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/Error.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/Error.java
@@ -32,9 +32,10 @@
 @XmlType ( name = "Error" )
 @JsonInclude( JsonInclude.Include.NON_NULL )
 @SuppressWarnings("gedcomx:no_id")
-@Schema(description = "The error code. Interpreted per RFC 2616, Section 10 (HTTP Status Code Definitions).")
+@Schema(description = "A common representation of an error on the FamilySearch platform.")
 public class Error {
 
+  // TODO: Fix links to RFC 2616 and RFC 2616, Section 10 (HTTP Status Code Definitions)
   @Schema(description = "The error code. Interpreted per RFC 2616, Section 10 (HTTP Status Code Definitions).")
   private Integer code;
 
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/Feature.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/Feature.java
@@ -37,10 +37,10 @@ public class Feature {
   @Schema(description = "A description of the feature.")
   private String description;
 
-  @Schema(description = "Whether the feature is enabled for the current request.")
+  @Schema(description = "True if the feature is enabled for the current request: false otherwise.")
   private Boolean enabled;
 
-  @Schema(description = "The date that this feature is scheduled to activate permanently.")
+  @Schema(description = "The date that this feature is scheduled to be enabled permanently.")
   private Date activationDate;
 
   /**
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/ChangeInfo.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/ChangeInfo.java
@@ -45,7 +45,7 @@ public class ChangeInfo {
   @Schema(description = "The type of the object to which the operation applies.")
   private URI objectType;
 
-  @Schema(description = "An optional modifier for the object to which the operation applies.")
+  @Schema(description = "An optional modifier for the object to which the operation applies. For example, if the object is a Fact, a modifier could be applied to indicate that fact applies to a person, couple, or child-and-parents relationship.")
   private URI objectModifier;
 
   @Schema(description = "The reason for the change.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/ChildAndParentsRelationship.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/ChildAndParentsRelationship.java
@@ -52,10 +52,10 @@ public class ChildAndParentsRelationship extends Subject {
   @Schema(description = "The child in the relationship.")
   private ResourceReference child;
 
-  @Schema(description = "The fact conclusions for the parent1.")
+  @Schema(description = "The fact conclusions for parent1.")
   private List<Fact> parent1Facts;
 
-  @Schema(description = "The fact conclusions for the parent2.")
+  @Schema(description = "The fact conclusions for parent2.")
   private List<Fact> parent2Facts;
 
   /**
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/DiscussionReference.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/DiscussionReference.java
@@ -37,10 +37,10 @@
 @JsonElementWrapper (name = "discussion-references")
 @XmlType ( name = "DiscussionReference" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "An data type that supports hypermedia controls (i.e. links).")
+@Schema(description = "A discussion reference")
 public final class DiscussionReference extends HypermediaEnabledData {
 
-  @Schema(description = "The URI to the resource. For more information, see Architecture of the World Wide Web, Volume One, Section 2")
+  @Schema(description = "The URI to the resource.")
   private URI resource;
 
   @Schema(description = "The attribution metadata for this discussion reference.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/MatchInfo.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/MatchInfo.java
@@ -44,19 +44,19 @@ public class MatchInfo {
   @Schema(description = "The way this match has been resolved.")
   private URI status;
 
-  @Schema(description = "tells if the match would add a person to the target system")
+  @Schema(description = "True if the match would add a person to the target system; false otherwise.")
   private Boolean addsPerson;
 
-  @Schema(description = "tells if the match would add a person to the target system who passes the 110-year rule")
+  @Schema(description = "True if the match would add a person to the target system who passes the 110-year rule; false otherwise.")
   private Boolean addsPerson110YearRule;
 
-  @Schema(description = "tells if the match would add a vital fact to the target system")
+  @Schema(description = "True if the match would add a vital fact to the target system; false otherwise.")
   private Boolean addsFact;
 
-  @Schema(description = "tells if the match would add a date or place to an existing vital fact")
+  @Schema(description = "True if the match would add a date or place to an existing vital fact; false otherwise.")
   private Boolean addsDateOrPlace;
 
-  @Schema(description = "tells if the destination has four or more people in the immediate family")
+  @Schema(description = "True if the destination has four or more people in the immediate family; false otherwise.")
   private Boolean hasFourOrMorePeople;
 
   public MatchInfo() {
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/Merge.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/Merge.java
@@ -35,7 +35,7 @@
 @JsonElementWrapper ( name = "merge" )
 @XmlType ( name = "Merge", propOrder = {"resourcesToDelete", "resourcesToCopy"} )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "The Merge")
+@Schema(description = "A merge.")
 public class Merge {
 
   @Schema(description = "List of resources to remove from the survivor person.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/MergeAnalysis.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/MergeAnalysis.java
@@ -35,13 +35,13 @@
 @JsonElementWrapper ( name = "mergeAnalysis" )
 @XmlType ( name = "MergeAnalysis", propOrder = {"survivorResources", "duplicateResources", "conflictingResources", "survivor", "duplicate"} )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "The Merge Analysis")
+@Schema(description = "A merge analysis.")
 public class MergeAnalysis {
 
-  @Schema(description = "List of resources to remove from the survivor person.")
+  @Schema(description = "List of survivor resources.")
   private List<ResourceReference> survivorResources;
 
-  @Schema(description = "List of resources to copy from the duplicate person to survivor person.")
+  @Schema(description = "List of duplicate resources.")
   private List<ResourceReference> duplicateResources;
 
   @Schema(description = "List of resources that are in conflict.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/MergeConflict.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/MergeConflict.java
@@ -32,13 +32,13 @@
 @JsonElementWrapper ( name = "mergeConflict" )
 @XmlType ( name = "MergeConflict", propOrder = {"survivorResource", "duplicateResource"} )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "The Merge Conflict")
+@Schema(description = "A merge conflict.")
 public class MergeConflict {
 
-  @Schema(description = "The survivor resource.")
+  @Schema(description = "The surviving person.")
   private ResourceReference survivorResource;
 
-  @Schema(description = "The duplicate resource.")
+  @Schema(description = "The duplicate person.")
   private ResourceReference duplicateResource;
 
   public MergeConflict() {
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/PersonInfo.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/PersonInfo.java
@@ -34,17 +34,17 @@
 @Schema(description = "Extra information about a person.")
 public class PersonInfo {
 
-  @Schema(description = "The person is editable by the current user.")
+  @Schema(description = "True if the person is editable by the current user; false otherwise.")
   private Boolean canUserEdit = false;
 
-  @Schema(description = "The person is visible to all sessions authenticated from any client.")
+  @Schema(description = "True if the person is visible to all sessions authenticated from any client; false otherwise.")
   private Boolean visibleToAll = true;
 
-  @Schema(description = "The person is only visible to sessions authenticated from a FamilySearch client.")
+  @Schema(description = "True if the person is only visible to sessions authenticated from a FamilySearch client; false otherwise.")
   private Boolean visibleToAllWhenUsingFamilySearchApps = true;
 
   // The treeId attribute is prototype only and may be removed or changed at any time
-  @Schema(description = "The tree id for this person.")
+  @Schema(description = "The tree id for this person. This attribute is prototype only and may be removed or changed at any time.")
   private String treeId;
 
   public PersonInfo() {
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/Tree.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ct/Tree.java
@@ -29,7 +29,7 @@
 @JsonElementWrapper( name = "tree" )
 @XmlType( name = "Tree" )
 @JsonInclude( JsonInclude.Include.NON_NULL )
-@Schema(description = "The Tree")
+@Schema(description = "A tree.")
 public class Tree {
 
   @Schema(description = "The tree id.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/discussions/Comment.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/discussions/Comment.java
@@ -30,7 +30,7 @@
 @XmlType ( name = "Comment", propOrder = { "text", "created", "contributor" } )
 @SuppressWarnings("gedcomx:no_id")
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "An data type that supports hypermedia controls (i.e. links).")
+@Schema(description = "A comment.")
 public class Comment extends HypermediaEnabledData {
 
   @Schema(description = "The text of the comment.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/discussions/Discussion.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/discussions/Discussion.java
@@ -38,7 +38,7 @@
 @JsonElementWrapper (name = "discussions")
 @XmlType ( name = "Discussion", propOrder = { "title", "details", "created", "contributor", "modified", "numberOfComments", "comments" } )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "A Discussion.")
+@Schema(description = "A discussion.")
 public class Discussion extends HypermediaEnabledData {
 
   @Schema(description = "The one-line summary or \"subject\" of the discussion.")
@@ -47,13 +47,13 @@ public class Discussion extends HypermediaEnabledData {
   @Schema(description = "The detailed text of the discussion.")
   private String details;
 
-  @Schema(description = "The date the discussion was created.")
+  @Schema(description = "The contributor who submitted this discussion.")
   private ResourceReference contributor;
 
   @Schema(description = "The date the discussion was created.")
   private Date created;
 
-  @Schema(description = "The date of last modification.")
+  @Schema(description = "Last date of any change to comments or discussion details.")
   private Date modified;    // last date of any change to comments or discussion details
 
   @Schema(description = "The number of comments associated with this discussion.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/Ordinance.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/Ordinance.java
@@ -48,7 +48,7 @@
 //    were not included by enunciate.  In order to get those OrdinanceStatusReason docs we add @XmlSeeAlso and @JsonSeeAlso at the class level.
 @XmlSeeAlso(OrdinanceStatusReason.class)
 @JsonSeeAlso(OrdinanceStatusReason.class)
-@Schema(description = "A genealogical conclusion.")
+@Schema(description = "An ordinance conclusion.")
 public class Ordinance extends Conclusion {
 
   @Schema(description = "The type of ordinance.")
@@ -69,7 +69,7 @@ public class Ordinance extends Conclusion {
   @Schema(description = "The sex type of the principal person in the ordinance.")
   private URI sexType;
 
-  @Schema(description = "The participants for this ordinance.")
+  @Schema(description = "The participants in this ordinance.")
   private List<OrdinanceParticipant> participants;
 
   @Schema(description = "Reservation for this ordinance.")
@@ -84,7 +84,7 @@ public class Ordinance extends Conclusion {
   @Schema(description = "The code for the temple at which the ordinance was performed.")
   private String templeCode;
 
-  @Schema(description = "The complete date of this ordinance.")
+  @Schema(description = "The completion date of this ordinance.")
   private Date completeDate;
 
   @Schema(description = "The full name of the person, generally in the native name form.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceActions.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceActions.java
@@ -31,20 +31,20 @@
 public class OrdinanceActions {
 
   // These have default values so they will always appear as either "true" or "false"
-  @Schema(description = "If this ordinance is reservable.")
+  @Schema(description = "True if this ordinance is reservable; false otherwise.")
   private Boolean reservable = false;
 
-  @Schema(description = "If this ordinance is unReservable.")
+  @Schema(description = "True if this ordinance is unReservable; false otherwise.")
   private Boolean unReservable = false;
 
-  @Schema(description = "If this ordinance is shareable.")
+  @Schema(description = "True if this ordinance is shareable; false otherwise.")
   private Boolean shareable = false;
 
-  @Schema(description = "If this ordinance is unShareable.")
+  @Schema(description = "True if this ordinance is unShareable; false otherwise.")
   private Boolean unShareable = false;
 
   // The private Boolean transferable is not supported yet
-  @Schema(description = "If this ordinance is transferable.")
+  @Schema(description = "True if this ordinance is transferable; false otherwise.")
   private Boolean printable = false;
 
 
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceParticipant.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceParticipant.java
@@ -32,7 +32,7 @@
 @JsonElementWrapper(name = "participants")
 @XmlType( name = "OrdinanceParticipant" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "The Ordinance Participant")
+@Schema(description = "The ordinance participant.")
 public class OrdinanceParticipant {
 
   @Schema(description = "The role type for this participant in the ordinance.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceReservation.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceReservation.java
@@ -34,13 +34,13 @@
 @JsonElementWrapper(name = "reservation")
 @XmlType( name = "OrdinanceReservation" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "The Ordinance Reservation")
+@Schema(description = "An ordinance reservation.")
 public class OrdinanceReservation {
 
   @Schema(description = "The owner associated with the ordinance reservation.")
   private ResourceReference owner;
 
-  @Schema(description = "The reserve timestamp for the ordinance reservation.")
+  @Schema(description = "The reservation timestamp for the ordinance reservation.")
   private Date reserveDate;                 // a java.util.Date
 
   @Schema(description = "The update timestamp for the ordinance reservation.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceRollup.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceRollup.java
@@ -33,13 +33,13 @@
 @JsonElementWrapper(name = "ordinanceRollups")
 @XmlType( name = "OrdinanceRollup", propOrder = {"type", "rollupStatus"})
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "A genealogical conclusion.")
+@Schema(description = "An ordinance rollup conclusion.")
 public class OrdinanceRollup extends Conclusion {
 
-  @Schema(description = "The type of ordinance")
+  @Schema(description = "The type of ordinance.")
   private URI type;
 
-  @Schema(description = "The rollup status of this ordinance")
+  @Schema(description = "The rollup status of this ordinance.")
   private URI rollupStatus;
 
 
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceSummary.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/ordinances/OrdinanceSummary.java
@@ -30,7 +30,7 @@
 @JsonElementWrapper(name = "ordinanceSummaries")
 @XmlType(name = "OrdinanceSummary", propOrder = {"notSharedReservationCount", "notSharedReservationLimit", "sharedReservationCount"})
 @JsonInclude (JsonInclude.Include.NON_NULL)
-@Schema(description = "Summary information regarding Ordinances.")
+@Schema(description = "Summary information regarding a user's ordinance.")
 public class OrdinanceSummary {
 
   @Schema(description = "The current number of reservations which have not been shared that a user has on their reservation list.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/places/FeedbackInfo.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/places/FeedbackInfo.java
@@ -33,7 +33,7 @@
 @JsonElementWrapper ( name = "feedbackInfo" )
 @XmlType ( name = "FeedbackInfo" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "Information about a a feedback submission about a place.")
+@Schema(description = "Information about a place feedback submission.")
 public class FeedbackInfo {
 
   @Schema(description = "The resolution of the feedback.")
@@ -45,7 +45,7 @@ public class FeedbackInfo {
   @Schema(description = "A reference to the place that was created based on this feedback, if any.")
   private ResourceReference place;
 
-  @Schema(description = "Some additional details about the resolution.")
+  @Schema(description = "Additional details about the resolution.")
   private String details;
 
   /**
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/places/PlaceAttribute.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/places/PlaceAttribute.java
@@ -18,6 +18,7 @@
 /**
  * @author Ryan Heaton
  */
+// TODO: Travis - This class is not used in the current version of the FamilySearch API.  It is not clear if it is still needed.
 public class PlaceAttribute {
 
   private String attributeId;
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/places/PlaceDescriptionInfo.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/places/PlaceDescriptionInfo.java
@@ -29,13 +29,13 @@
 @Schema(description = "Information about a place description.")
 public class PlaceDescriptionInfo {
 
-  @Schema(description = "The zoom level for this place description.")
+  @Schema(description = "The zoom level of this place description.")
   private Integer zoomLevel;
 
-  @Schema(description = "The type of this related place description.")
+  @Schema(description = "The type of this related place description. This attribute is only relevant \"related place descriptions.\"")
   private String relatedType;
 
-  @Schema(description = "The sub-type of this related place description.")
+  @Schema(description = "The sub-type of this related place description. This attribute is only relevant \"related place descriptions.\"")
   private String relatedSubType;
 
   /**
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/records/AlternateDate.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/records/AlternateDate.java
@@ -23,13 +23,13 @@
 import jakarta.xml.bind.annotation.XmlRootElement;
 
 /**
- * An ordinance reservation.
+ * An alternate date.
  *
  */
 @XmlRootElement
 @JsonElementWrapper ( name = "altDates" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "An ordinance reservation.")
+@Schema(description = "An alternate date.")
 public class AlternateDate extends Date {
 
 }
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/records/AlternatePlaceReference.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/records/AlternatePlaceReference.java
@@ -23,13 +23,13 @@
 import jakarta.xml.bind.annotation.XmlRootElement;
 
 /**
- * An ordinance reservation.
+ * An alternate place reference.
  *
  */
 @XmlRootElement
 @JsonElementWrapper ( name = "altPlaces" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "An ordinance reservation.")
+@Schema(description = "An alternate place reference.")
 public class AlternatePlaceReference extends PlaceReference {
 
 }
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/records/FieldInfo.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/records/FieldInfo.java
@@ -41,13 +41,13 @@ public class FieldInfo implements Serializable {
   @Schema(description = "The display label for the field.")
   private String displayLabel;
 
-  @Schema(description = "Whether the field is standard.")
+  @Schema(description = "True if the field is standard; false otherwise.")
   private boolean standard;
 
-  @Schema(description = "Whether the field is editable.")
+  @Schema(description = "True if the field is editable; false otherwise.")
   private boolean editable;
 
-  @Schema(description = "Whether the field is displayable.")
+  @Schema(description = "True if the field is displayable; false otherwise.")
   private boolean displayable;
 
   @Schema(description = "The element types for the field.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/search/Facet.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/search/Facet.java
@@ -30,7 +30,7 @@
 @JsonElementWrapper(name="facets")
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @XmlType( name = "Facet" )
-@Schema(description = "A facet in a search result.")
+@Schema(description = "A facet.")
 public class Facet {
 
   @Schema(description = "The localized name of this facet.")
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/vocab/VocabConcept.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/vocab/VocabConcept.java
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/vocab/VocabTerm.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/vocab/VocabTerm.java
diff --git a/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/vocab/VocabTranslation.java b/extensions/familysearch/familysearch-api-model/src/main/java/org/familysearch/platform/vocab/VocabTranslation.java
diff --git a/gedcomx-model/src/main/java/org/gedcomx/Gedcomx.java b/gedcomx-model/src/main/java/org/gedcomx/Gedcomx.java
diff --git a/gedcomx-model/src/main/java/org/gedcomx/links/Link.java b/gedcomx-model/src/main/java/org/gedcomx/links/Link.java
