From 7c2ecd8658fe0be63262f7502618144935798daf Mon Sep 17 00:00:00 2001
From: wvengen <dev-voko@willem.engen.nl>
Date: Fri, 6 Jun 2014 16:34:07 +0200
Subject: [PATCH] add some model api docs

---
 app/models/article.rb          | 47 ++++++++++++++++++++++++++++++----
 app/models/article_category.rb | 10 ++++++++
 app/models/article_price.rb    | 28 +++++++++++++++++---
 3 files changed, 76 insertions(+), 9 deletions(-)

diff --git a/app/models/article.rb b/app/models/article.rb
index 34b346ed..b9cd5879 100644
--- a/app/models/article.rb
+++ b/app/models/article.rb
@@ -1,14 +1,51 @@
 # encoding: utf-8
 class Article < ActiveRecord::Base
 
+  # @!attribute name
+  #   @return [String] Article name
+  # @!attribute unit
+  #   @return [String] Unit, e.g. +kg+, +2 L+ or +5 pieces+.
+  # @!attribute note
+  #   @return [String] Short line with optional extra article information.
+  # @!attribute availability
+  #   @return [Boolean] Whether this article is available within the Foodcoop.
+  # @!attribute manufacturer
+  #   @return [String] Original manufacturer.
+  # @!attribute origin
+  #   Where the article was produced.
+  #   ISO 3166-1 2-letter country code, optionally prefixed with region.
+  #   E.g. +NL+ or +Sicily, IT+ or +Berlin, DE+.
+  #   @return [String] Production origin.
+  #   @see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+  # @!attribute price
+  #   @return [Number] Net price
+  #   @see ArticlePrice#price
+  # @!attribute tax
+  #   @return [Number] VAT percentage (10 is 10%).
+  #   @see ArticlePrice#tax
+  # @!attribute deposit
+  #   @return [Number] Deposit
+  #   @see ArticlePrice#deposit
+  # @!attribute unit_quantity
+  #   @return [Number] Number of units in wholesale package (box).
+  #   @see ArticlePrice#unit_quantity
+  # @!attribute order_number
+  # Order number, this can be used by the supplier to identify articles.
+  # This is required when using the shared database functionality.
+  #   @return [String] Order number.
+  # @!attribute article_category
+  #   @return [ArticleCategory] Category this article is in.
+  belongs_to :article_category
+  # @!attribute supplier
+  #   @return [Supplier] Supplier this article belongs to.
+  belongs_to :supplier
+  # @!attribute article_prices
+  #   @return [Array<ArticlePrice>] Price history (current price first).
+  has_many :article_prices, -> { order("created_at DESC") }
+
   # Replace numeric seperator with database format
   localize_input_of :price, :tax, :deposit
 
-  # Associations
-  belongs_to :supplier
-  belongs_to :article_category
-  has_many :article_prices, -> { order("created_at DESC") }
-
   scope :undeleted, -> { where(deleted_at: nil) }
   scope :available, -> { undeleted.where(availability: true) }
   scope :not_in_stock, -> { where(type: nil) }
diff --git a/app/models/article_category.rb b/app/models/article_category.rb
index c93e1c31..cc99ae35 100644
--- a/app/models/article_category.rb
+++ b/app/models/article_category.rb
@@ -1,4 +1,13 @@
+# Article category
 class ArticleCategory < ActiveRecord::Base
+
+  # @!attribute name
+  #   @return [String] Title of the category.
+  # @!attrubute description
+  #   @return [String] Description (currently unused)
+
+  # @!attribute articles
+  #   @return [Array<Article>] Articles with this category.
   has_many :articles
 
   validates :name, :presence => true, :uniqueness => true, :length => { :in => 2..20 }
@@ -7,6 +16,7 @@ class ArticleCategory < ActiveRecord::Base
 
   protected
 
+  # Deny deleting the category when there are associated articles.
   def check_for_associated_articles
     raise I18n.t('activerecord.errors.has_many_left', collection: Article.model_name.human) if articles.undeleted.exists?
   end
diff --git a/app/models/article_price.rb b/app/models/article_price.rb
index 29e8d507..67e4df76 100644
--- a/app/models/article_price.rb
+++ b/app/models/article_price.rb
@@ -1,21 +1,41 @@
 class ArticlePrice < ActiveRecord::Base
 
+  # @!attribute price
+  #   @return [Number] Net price
+  #   @see Article#price
+  # @!attribute tax
+  #   @return [Number] VAT percentage
+  #   @see Article#tax
+  # @!attribute deposit
+  #   @return [Number] Deposit
+  #   @see Article#deposit
+  # @!attribute unit_quantity
+  #   @return [Number] Number of units in wholesale package (box).
+  #   @see Article#unit
+  #   @see Article#unit_quantity
+  # @!attribute article
+  #   @return [Article] Article this price is about.
   belongs_to :article
+  # @!attribute order_articles
+  #   @return [Array<OrderArticle>] Order articles this price is associated with.
   has_many :order_articles
 
+  localize_input_of :price, :tax, :deposit
+
   validates_presence_of :price, :tax, :deposit, :unit_quantity
   validates_numericality_of :price, :greater_than_or_equal_to => 0
   validates_numericality_of :unit_quantity, :greater_than => 0
   validates_numericality_of :deposit, :tax
 
-  localize_input_of :price, :tax, :deposit
-
-  # The financial gross, net plus tax and deposit.
+  # Gross price = net price + deposit + tax.
+  # @return [Number] Gross price.
+  # @todo remove code-duplication with Article
   def gross_price
     ((price + deposit) * (tax / 100 + 1)).round(2)
   end
 
-  # The price for the foodcoop-member.
+  # @return [Number] Price for the foodcoop-member.
+  # @todo remove code-duplication with Article
   def fc_price
     (gross_price  * (FoodsoftConfig[:price_markup] / 100 + 1)).round(2)
   end