From 4ac9d2a2426764076ae81a619ff84c85f1410f51 Mon Sep 17 00:00:00 2001
From: mjy <diapriid@gmail.com>
Date: Thu, 4 Dec 2014 11:09:49 -0600
Subject: [PATCH] Docs for DataAttributes.

---
 app/models/data_attribute.rb     | 20 +++++++++++++++++++
 app/models/import_attribute.rb   | 33 ++++++++++++++++++++++++++++++++
 app/models/internal_attribute.rb |  9 +++++++++
 3 files changed, 62 insertions(+)

diff --git a/app/models/data_attribute.rb b/app/models/data_attribute.rb
index 3fc4082d7e..45d82e5d64 100644
--- a/app/models/data_attribute.rb
+++ b/app/models/data_attribute.rb
@@ -1,3 +1,23 @@
+# A data attribute is used to attach an arbitrary predicate/literal pair to a data instance, essentially creating a user-defined triple.
+#
+# DataAttribute is only instantiated through its subclasses ImportAttribute or InternalAttribute
+#
+# @!attribute value 
+#   @return [String]
+#   The user provided data, e.g. RFD literal or objectobject, i.e. RDF literal, i.e. data in a cell of a spreadsheet.  Always required.
+#
+# @!attribute attribute_subject_id 
+#   @return [Integer]
+#   The id of the subject (Rails polymorphic relationship). 
+#
+# @!attribute attribute_subject_type
+#   @return [String]
+#   THe class of the subject (Rails polymorphic relationship).
+#
+# @!attribute type 
+#   @return [String]
+#   The type of DataAttribute (Rails STI). 
+#
 class DataAttribute < ActiveRecord::Base
   include Housekeeping::Users
   include Shared::IsData 
diff --git a/app/models/import_attribute.rb b/app/models/import_attribute.rb
index 9ede5cb09b..c6ab9e2419 100644
--- a/app/models/import_attribute.rb
+++ b/app/models/import_attribute.rb
@@ -1,3 +1,36 @@
+
+# The DataAttribute that has an externally referenced (and likely undefined) predicate.  
+#
+# ImportAttributes are used to attach data to other TW data in cases where the user is unclear
+# as to the meaning of the related data.  For example, if a spreadsheet is batch imported it 
+# might be that 4 of the 10 columns could be mapped to a concept, say CollectionObject, in TW.  The remaining
+# 6 columns do not nicely map.  If the user wants to associate the data from those 6 columns she can
+# include them as import attributes.  In this case the column header is the @import_predicate.  
+#
+# Use with caution, typically as a means to maintain legacy values on import.
+#
+# For example: 
+#
+#  attribute_subject  import_predicate       value
+#  @some_otu          "times_seen_in_lake"   14
+#
+# or
+#
+#  attribute_subject  import_predicate       value
+#  @some_specimen     'has_part'            'some_uri'
+#
+# or
+#
+#  attribute_subject       import_predicate  value
+#  @some_collecting_event  "micro_habitat"   "north side of wet rock"
+#
+#
+#
+# @!attribute import_predicate 
+#   @return [string]
+#   The predicate literal.  For example a column header.  
+#
+#
 class ImportAttribute < DataAttribute
   include Housekeeping::Users
   validates_presence_of :import_predicate
diff --git a/app/models/internal_attribute.rb b/app/models/internal_attribute.rb
index f3eaca40f2..d2b36377ad 100644
--- a/app/models/internal_attribute.rb
+++ b/app/models/internal_attribute.rb
@@ -1,3 +1,12 @@
+# The DataAttribute that has a Predicate that is internally defined in TaxonwWorks.
+#
+# Internal attributes have stronger semantics that ImportAttributes in that the user has had to first
+# create a Predicate (which is a controlled vocabulary subclass), which in turn requires a definition. 
+
+# @!attribute controlled_vocabulary_term_id 
+#   @return [id]
+#   The the id of the ControlledVocabularyTerm::Predicate.  Term is referenced as .predicate.
+#
 class InternalAttribute < DataAttribute 
   include Housekeeping
   belongs_to :predicate, foreign_key: :controlled_vocabulary_term_id, inverse_of: :internal_attributes