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]

6 files changed, 191 insertions, 0 deletions

diff --git a/wikipedia/ArticleList.js b/wikipedia/ArticleList.js
index bc7dc03..7ce2639 100644
--- a/wikipedia/ArticleList.js
+++ b/wikipedia/ArticleList.js
@@ -34,6 +34,13 @@ const ArticleList = new Lang.Class({
         this.add(this._grid);
     },
 
+    /**
+     * Method: setArticles
+     * Set articles to display in this widget
+     *
+     * Parameters:
+     *   articles - An array of <ArticleModels>
+     */
     setArticles: function(articles) {
         // Remove all existing article links
         this._grid.get_children().forEach(function(element, index, obj) {
diff --git a/wikipedia/models/article_model.js b/wikipedia/models/article_model.js
index 8cba140..5c6cc15 100644
--- a/wikipedia/models/article_model.js
+++ b/wikipedia/models/article_model.js
@@ -21,25 +21,74 @@ const ArticleModel = new Lang.Class({
         this.parent(params);
     },
 
+    /**
+     * Method: setCategories
+     * Give this article a list of categories or tags
+     *
+     * Parameters:
+     *   categoryList - an array of strings signifying category IDs
+     *
+     * Makes this article's categories the list signified by _categoryList_,
+     * wiping out any categories that were previously set.
+     */
     setCategories: function (categoryList) {
         this._categoryList = categoryList;
     },
 
+    /**
+     * Method: addCategory
+     * Attach a category or tag to this article
+     *
+     * Parameters:
+     *   categoryId - a string signifying a category ID
+     *
+     * Tags this article with _categoryID_.
+     * Does nothing if this article is already tagged with that ID.
+     */
     addCategory: function (categoryId) {
         if (!this.hasCategory(categoryId))
             this._categoryList.push(categoryId);
     },
 
+    /**
+     * Method: getCategories
+     * List of this article's categories or tags
+     *
+     * Returns:
+     *   An array of strings signifying category IDs.
+     */
     getCategories: function () {
         return this._categoryList;
     },
 
+    /**
+     * Method: hasCategory
+     * Whether this article is tagged with a particular ID
+     *
+     * Parameters:
+     *   categoryId - a string signifying a category ID
+     *
+     * Returns:
+     *   true if this article is tagged with _categoryId_, false if not.
+     */
     hasCategory: function (categoryId) {
         return this._categoryList.indexOf(categoryId) != -1;
     }
 
 });
 
+/**
+ * Function: newFromJson
+ * Construct a new <ArticleModel> from data exported by the CMS
+ *
+ * Parameters:
+ *   json - a category object created by parsing the JSON file
+ *
+ * Returns:
+ *   A newly created <ArticleModel>.
+ *
+ * See <DomainWikiModel.loadFromJson> for the structure of the JSON object.
+ */
 function newFromJson(json) {
     let retval = new ArticleModel({
         title: json['title'],
diff --git a/wikipedia/models/category_model.js b/wikipedia/models/category_model.js
index dea4ae3..a17c9ac 100644
--- a/wikipedia/models/category_model.js
+++ b/wikipedia/models/category_model.js
@@ -8,6 +8,13 @@ const CategoryModel = new Lang.Class({
     Name: "CategoryModel",
     Extends: GObject.Object,
    	Properties: {
+        /**
+         * Property: id
+         * String for referring to this category internally
+         *
+         * Can generally be equal to <CategoryModel.title>, though that is not
+         * required.
+         */
         'id': GObject.ParamSpec.string('id', 'ID string',
             'String for referring to this category internally',
             GObject.ParamFlags.READWRITE | GObject.ParamFlags.CONSTRUCT_ONLY,
@@ -27,6 +34,15 @@ const CategoryModel = new Lang.Class({
         'is-main-category': GObject.ParamSpec.boolean('is-main-category', 'Is Main Category boolean', 'Flag denoting whether this category is the main category for this app', 
             GObject.ParamFlags.READWRITE | GObject.ParamFlags.CONSTRUCT_ONLY,
                 false),
+        /**
+         * Property: has_articles
+         * Whether this category contains articles
+         *
+         * This property is not computed in any way, but is set by the library
+         * model when loading from a JSON file.
+         * This value is used to determine whether a category should be
+         * clickable, for example.
+         */
         'has-articles': GObject.ParamSpec.boolean('has-articles',
             'Has articles',
             'Indicates whether category has any articles under it',
@@ -39,12 +55,31 @@ const CategoryModel = new Lang.Class({
         this.parent(params);
     },
 
+    /**
+     * Method: addSubcategory
+     * Add a subcategory to this model
+     *
+     * Parameters:
+     *   modelObj - another <CategoryModel> that is to be a subcategory of this
+     *   one.
+     *
+     * Does nothing if this category already has a subcategory with _modelObj_'s
+     * ID.
+     */
     addSubcategory: function (modelObj) {
         if (!this._subcategories.hasOwnProperty(modelObj.id)) {
             this._subcategories[modelObj.id] = modelObj;
         }
     },
 
+    /**
+     * Method: getSubcategories
+     * List this model's subcategories
+     *
+     * Returns:
+     *   An array of <CategoryModels> representing this category's
+     *   subcategories, or an empty array if there are none.
+     */
     getSubcategories: function () {
         let retval = [];
         for (let id in this._subcategories) {
@@ -54,6 +89,18 @@ const CategoryModel = new Lang.Class({
     }
 });
 
+/**
+ * Function: newFromJson
+ * Construct a new <CategoryModel> from data exported by the CMS
+ *
+ * Parameters:
+ *   json - a category object created by parsing the JSON file
+ *
+ * Returns:
+ *   A newly created <CategoryModel> with no subcategories.
+ *
+ * See <DomainWikiModel.loadFromJson> for the structure of the JSON object.
+ */
 function newFromJson(json) {
     let retval = new CategoryModel({
         id: json['category_name'],
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;
     }
diff --git a/wikipedia/views/domain_wiki_view.js b/wikipedia/views/domain_wiki_view.js
index 0647ee4..bb68c7e 100644
--- a/wikipedia/views/domain_wiki_view.js
+++ b/wikipedia/views/domain_wiki_view.js
@@ -177,6 +177,10 @@ const DomainWikiView = new Lang.Class({
         this._article_back_button.label = category.title.toUpperCase();
     },
 
+    /**
+     * Method: set_article_info
+     * Proxy method to set the article displaying on the article page
+     */
     set_article_info: function (title, uri) {
         // Note: Must set article title first
         this._article_view.article_title = title;
diff --git a/wikipedia/widgets/category_selector_view.js b/wikipedia/widgets/category_selector_view.js
index 66ef15e..674e563 100644
--- a/wikipedia/widgets/category_selector_view.js
+++ b/wikipedia/widgets/category_selector_view.js
@@ -24,6 +24,14 @@ const CategorySelectorView = new Lang.Class({
         this.parent(props);
     },
 
+    /**
+     * Method: setCategories
+     * Create buttons in this view for a list of categories to display
+     *
+     * Parameters:
+     *   categories - An array of <CategoryModels>
+     *
+     */
     setCategories: function(categories) {
         categories.forEach(function (category) {
             let button = new CategoryButton.CategoryButton({