wiki: Add documentation for all new and changed API

For good code hygiene, let's make sure we document all new and changed
APIs.

[endlessm/eos-sdk#367]

1 files changed, 76 insertions, 0 deletions

diff --git a/wikipedia/models/domain_wiki_model.js b/wikipedia/models/domain_wiki_model.js
index dbd0774..b5ced4e 100644
--- a/wikipedia/models/domain_wiki_model.js
+++ b/wikipedia/models/domain_wiki_model.js
@@ -20,6 +20,48 @@ const DomainWikiModel = new Lang.Class({
         this.parent(params);
     },
 
+    /**
+     * Method: loadFromJson
+     * Populate the model from the CMS's exported JSON file
+     *
+     * Parameters:
+     *   json - an object created by parsing the JSON file
+     *
+     * Call this once, when creating the model, to populate it using the JSON
+     * file defining the categories and articles.
+     * The JSON file adheres to the following format:
+     *
+     * > <MAIN> =
+     * > {
+     * >     "categories": [ <CATEGORY>, <CATEGORY>, ... ],
+     * >     "articles": [ <ARTICLE>, <ARTICLE>, ... ]
+     * > }
+     * > <CATEGORY> =
+     * > {
+     * >     "category_name": <string>,
+     * >     "content_text": <string>,
+     * >     "image_file": <string>,
+     * >     "image_thumb_uri": <string>,
+     * >     "is_main_category": <boolean>,
+     * >     "subcategories": [ <string>, <string>, ... ]
+     * > }
+     *
+     * "subcategories" is a list of "category_name" strings from other
+     * categories.
+     * "subcategories" can be empty.
+     * "is_main_category" will probably disappear from a future version.
+     *
+     * > <ARTICLE> =
+     * > {
+     * >     "title": <string>,
+     * >     "url": <string>,
+     * >     "categories": [ <string>, <string>, ... ],
+     * > }
+     *
+     * "categories" is a list of "category_name" strings from the categories this
+     * article is associated with.
+     * "categories" can be empty, but generally should not.
+     */
     loadFromJson: function (json) {
         // Load list of articles
         this._articles = json['articles'].map(function (article) {
@@ -51,10 +93,25 @@ const DomainWikiModel = new Lang.Class({
         return this._linked_articles;
     },
 
+    /**
+     * Method: getArticles
+     * Articles available in this library
+     */
     getArticles: function () {
         return this._articles;
     },
 
+    /**
+     * Method: getArticlesForCategory
+     * Articles belonging to a category in this library
+     *
+     * Parameters:
+     *   id - The string ID of a category
+     *
+     * Returns:
+     *   An array of <ArticleModels> belonging to the category signified by _id_
+     *   or an empty array if there were none or _id_ was not found
+     */
     getArticlesForCategory: function (id) {
         return this._articles.filter(function (article) {
             return article.getCategories().indexOf(id) != -1;
@@ -69,10 +126,29 @@ const DomainWikiModel = new Lang.Class({
         });
     },
 
+    /**
+     * Method: getCategory
+     * Category corresponding to a string ID
+     *
+     * Parameters:
+     *   id - The string ID of a category
+     *
+     * Returns:
+     *   A <CategoryModel> that corresponds to _id_, or undefined if _id_ was
+     *   not found.
+     */
     getCategory: function (id) {
         return this._categories[id];
     },
 
+    /**
+     * Method: getMainCategory
+     * Category marked as "main" for this library
+     *
+     * Returns:
+     *   A <CategoryModel> that has been marked as the "main" category, or null
+     *   if the main category has not been set yet.
+     */
     getMainCategory: function () {
         return this._mainCategory;
     }