Add jsdoc comments to history models

kfet/static/kfet/js/kfet.api.js

@@ -85,7 +85,18 @@ class Config {
  * Models without API support:
  * {@link Models.Statement},
  * {@link Models.ArticleCategory},
- * {@link Models.Article}.
+ * {@link Models.Article},
+ * {@link Models.HistoryGroup},
+ * {@link Models.OperationGroup},
+ * {@link Models.TransferGroup},
+ * {@link Models.Operation},
+ * {@link Models.Purchase},
+ * {@link Models.SpecialOperation},
+ * {@link Models.Transfer}.
+ * <br>
+ * Implementations of ModelForest:
+ * {@link Models.ArticleList}
+ * {@link Models.OperationList}
  *
  * @namespace Models
  */
@@ -168,8 +179,7 @@ class ModelObject {
     }
 
     /**
-     * Returns a string value for the model, to use in comparisons
+     * Compares two ModelObject instances.
-     * @see {@link Models.TreeNode.compare|TreeNode.compare}
      */
     static compare(a, b) {
         return a.id - b.id;
@@ -569,13 +579,6 @@ class Day extends ModelObject {
      */
     static get default_data() { return {'id': '', 'date': moment()}; }
 
-    /**
-     * Verbose name for Day model.
-     * @default <tt>'day'</tt>
-     * @see {@link Models.ModelObject.verbose_name[ModelObject.verbose_name}
-     */
-    static get verbose_name() { return 'day'; }
-
     /**
      * @default {@link Formatters.DayFormatter}
      */
@@ -600,22 +603,34 @@ class Day extends ModelObject {
 }
 
 /**
- * HistoryGroup model. Should not be used without extending.
+ * HistoryGroup model. Should not be used directly.
  * @extends Models.ModelObject
  * @memberof Models
  */
 class HistoryGroup extends ModelObject {
+
+    /**
+     * Properties assowiated to HistoryGroup instances.
+     * @default <tt>['id', 'at', 'comment', 'valid_by']</tt>
+     * @see {@link Models.ModelObject.props|ModelObject.props}
+     */
     static get props() {
         return ['id', 'at', 'comment', 'valid_by'];
     }
 
+    /**
+     * Default values for HistoryGroup model instances
+     * @default <tt>{ 'id': 0, 'at': moment(), 'comment': '', 
+            'valid_by': '' }</tt>
+     * @see {@link Models.ModelObject.default_data|ModelObject.default_data}
+     */
     static get default_data() {
         return {'id': 0, 'at': moment(), 'comment': '', 
             'valid_by': '',};
     }
 
     /**
-     * Comparison function between OperationGroup model instances.
+     * Comparison function between HistoryGroup model instances.
      * @see {@link Models.ModelObject.compare|ModelObject.compare}
      */
     static compare(a, b) {
@@ -639,8 +654,7 @@ class OperationGroup extends HistoryGroup {
 
     /**
      * Properties associated with an opegroup.
-     * @default <tt>['id', 'amount', 'at', 'is_cof',
+     * @default <tt>{@link Models.HistoryGroup.props|HistoryGroup.props} + ['is_cof', 'trigramme']</tt>
-     * 'comment', 'trigramme', 'valid_by', 'day', 'type']</tt>
      * @see {@link Models.ModelObject.props|ModelObject.props}
      */
     static get props() {
@@ -649,8 +663,8 @@ class OperationGroup extends HistoryGroup {
 
     /**
      * Default values for OperationGroup instances.
-     * @default <tt>{'id': 0, 'amount': 0, 'at': moment(), 'is_cof': false, 
+     * @default <tt>{@link Models.HistoryGroup.default_data|HistoryGroup.default_data} + 
-            'comment': '', 'trigramme': '', 'valid_by': ''}</tt>
+     * {'amount': 0, 'is_cof': false, 'trigramme': ''}</tt>
      * @see {@link Models.ModelObject.default_data|ModelObject.default_data}
      */
     static get default_data() {
@@ -693,9 +707,7 @@ class Operation extends ModelObject {
 
     /**
      * Properties associated to an operation.
-     * @default <tt>['id', 'type', 'amount', 'article_name', 'article_nb',
+     * @default <tt>['id', 'amount', 'canceled_at', 'canceled_by']</tt>
-     *  'is_checkout', 'addcost_amount', 'addcost_for', 'canceled_at',
-     *  'canceled_by', 'from_acc', 'to_acc', 'opegroup']</tt>
      * @see {@link Models.ModelObject.props|ModelObject.props}
      */
     static get props() {
@@ -704,9 +716,7 @@ class Operation extends ModelObject {
 
     /**
      * Default values for Operation model instances
-     * @default <tt>{'id': 0, 'type': '', 'amount': 0, 'article_name': '', 
+     * @default <tt>{'id': '', 'amount': 0, 'canceled_at': undefined, 'canceled_by': '' }</tt>
-     * 'article_nb': 0, 'is_checkout': false, 'addcost_amount': 0, 
-     * 'addcost_for': '', 'canceled_at': undefined, 'canceled_by': ''}</tt>
      * @see {@link Models.ModelObject.default_data|ModelObject.default_data}
      */
     static get default_data() {
@@ -725,13 +735,33 @@ class Operation extends ModelObject {
     }
 }
 
+/**
+ * Purchase model. Cannot be accessed through API.
+ * @extends Models.Operation
+ * @memberof Models
+ */
 class Purchase extends Operation {
+
+    /**
+     * Additional properties for purchases.
+     * @default <tt>{@link Models.Operation.props|Operation.props} + ['article_name', 'article_nb', 
+     * 'addcost_amount', 'addcost_for']</tt>
+     * @see {@link Models.ModelObject.props|ModelObject.props}
+     */
     static get props() {
         return Operation.props.concat(
                 ['article_name', 'article_nb', 'addcost_amount', 'addcost_for']
                 );
     }
 
+    /**
+     * Default values for Operation model instances
+     * @default <tt>{@link Models.Operation.default_data|Operation.default_data} + {
+     *      'article_name': '', 'article_nb': 0,
+     *      'addcost_amount': 0, 'addcost_for': ''
+     *  }
+     * @see {@link Models.ModelObject.default_data|ModelObject.default_data}
+     */
     static get default_data() {
         return $.extend({}, Operation.default_data, {
             'article_name': '', 'article_nb': 0,
@@ -739,34 +769,75 @@ class Purchase extends Operation {
         });
     }
 
+    /**
+     * @default {@link Formatters.PurchaseFormatter}
+     */
     formatter() {
         return PurchaseFormatter;
     }
 }
 
+/**
+ * Special operation model. Cannot be accessed through API.
+ * @extends Models.Operation
+ * @memberof Models
+ */
 class SpecialOperation extends Operation {
+
+    /**
+     * Additional properties for special operations.
+     * @default <tt>{@link Models.Operation.props|Operation.props} + ['type', 'is_checkout']</tt>
+     * @see {@link Models.ModelObject.props|ModelObject.props}
+     */
     static get props() {
         return Operation.props.concat(['type', 'is_checkout']);
     }
 
+    /**
+     * Default values for SpecialOperation model instances
+     * @default <tt>{@link Models.Operation.default_data|Operation.default_data} + {'type': '', 'is_checkout': false}
+     * @see {@link Models.ModelObject.default_data|ModelObject.default_data}
+     */
     static get default_data() {
         return $.extend({}, Operation.default_data, {'type': '', 'is_checkout': false});
     }
 
+    /**
+     * @default {@link Formatters.SpecialOpeFormatter}
+     */
     formatter() {
         return SpecialOpeFormatter;
     }
 }
 
+/**
+ * Transfer model. Cannot be accessed through API.
+ * @exetends Models.Operation
+ * @memberof Models
+ */
 class Transfer extends Operation {
+
+    /**
+     * Additional properties for transfers.
+     * @default <tt>{@link Models.Operation.props|Operation.props} + ['from_acc', 'to_acc']</tt>
+     * @see {@link Models.ModelObject.props|ModelObject.props}
+     */
     static get props() {
         return Operation.props.concat(['from_acc', 'to_acc']);
     }
 
+    /**
+     * Default values for Transfer model instances
+     * @default <tt>{@link Models.Operation.default_data|Operation.default_data} + {'from_acc': '', 'to_acc': ''}
+     * @see {@link Models.ModelObject.default_data|ModelObject.default_data}
+     */
     static get default_data() {
         return $.extend({}, Operation.default_data, {'from_acc': '', 'to_acc': ''});
     }
 
+    /**
+     * @default {@link Formatters.TransferFormatter}
+     */
     formatter() {
         return TransferFormatter;
     }
@@ -1346,7 +1417,6 @@ class ArticleCategoryFormatter extends Formatter {
  * @memberof Formatters
  * @extends Formatters.Formatter
  */
-
 class ArticleFormatter extends Formatter {
 
     /**
@@ -1357,6 +1427,9 @@ class ArticleFormatter extends Formatter {
         return Article.props;
     }
 
+    /**
+     * <tt>s.price</tt> converted to UKF.
+     */
     static prop_price(s) {
         return amountToUKF(s.price, true);
     }
@@ -1368,10 +1441,13 @@ class ArticleFormatter extends Formatter {
         };
     }
 
-    static attr_data_stock(a) {
+    /**
-        if      (a.stock >= 5)  { return this._data_stock.ok; }
+     * Value of data_stock attribute based on s.stock.
-        else if (a.stock >= -5) { return this._data_stock.low; }
+     */
-        else /* a.stock < -5 */ { return this._data_stock.neg; }
+    static attr_data_stock(s) {
+        if      (s.stock >= 5)  { return this._data_stock.ok; }
+        else if (s.stock >= -5) { return this._data_stock.low; }
+        else /* s.stock < -5 */{ return this._data_stock.neg; }
     }
 }
 
@@ -1381,13 +1457,18 @@ class ArticleFormatter extends Formatter {
  * @memberof Formatters
  * @todo don't display trigramme in account_read
  */
-
 class HistoryGroupFormatter extends Formatter {
 
+    /**
+     * <tt>a.time<tt> formatted as <tt>HH:mm:ss</tt>
+     */
     static prop_time(a) {
         return a.at.format('HH:mm:ss');
     }
 
+    /**
+     * <tt>valid_by</tt> property is displayed only if <tt>a.valid_by</tt> is nonempty.
+     */
     static prop_valid_by(a) {
         if (a.valid_by)
             return 'Par '+a.valid_by;
@@ -1396,24 +1477,46 @@ class HistoryGroupFormatter extends Formatter {
     }
 }
 
+/**
+ * @memberof Formatters
+ * @extends Formatters.HistoryGroupFormatter
+ */
 class TransferGroupFormatter extends HistoryGroupFormatter {
     
+    /**
+     * Properties renderable to html.
+     * @default {@link Models.TransferGroup.props} <tt> + ['infos', 'time']</tt>
+     */
     static get props() {
         return TransferGroup.props.concat(['infos', 'time']);
     }
 
+    /**
+     * Generic info for transfergroups.
+     */
     static prop_infos(a) {
         //TODO find better thing to put here
         return 'Transferts';
     }
 }
 
+/**
+ * @memberof Formatters
+ * @extends Formatters.HistoryGroupFormatter
+ */
 class OpegroupFormatter extends HistoryGroupFormatter {
 
+    /**
+     * Properties renderable to html.
+     * @default {@link Models.OperationGroup.props} <tt> + ['time']</tt>
+     */
     static get props() {
         return OperationGroup.props.concat(['time']);
     }
 
+    /**
+     * <tt>a.amount</tt> displayed according to <tt>a.is_cof</tt> and <tt>a.trigramme</tt> values.
+     */
     static prop_amount(a) {
         return amountDisplay(a.amount, a.is_cof, a.trigramme);
     }
@@ -1423,7 +1526,6 @@ class OpegroupFormatter extends HistoryGroupFormatter {
  * @extends Formatters.Formatter
  * @memberof Formatters
  */
-
 class DayFormatter extends Formatter {
     
     /**
@@ -1434,6 +1536,9 @@ class DayFormatter extends Formatter {
         return Day.props;
     }
 
+    /**
+     * <tt>a.date</tt> formatted as <tt>D MMMM</tt>
+     */
     static prop_date(a) {
         return a.date.format('D MMMM');
     }
@@ -1445,6 +1550,10 @@ class DayFormatter extends Formatter {
  */
 class OperationFormatter extends Formatter {
 
+    /**
+     * Properties renderable to html.
+     * @default <tt>['amount', 'infos1', 'infos2', 'addcost', 'canceled']</tt>
+     */
     static get props() {
         return ['amount', 'infos1', 'infos2', 'addcost', 'canceled'];
     }
@@ -1453,10 +1562,16 @@ class OperationFormatter extends Formatter {
         return ['canceled'];
     }
 
+    /**
+     * <tt>a.amount</tt> displayed according to <tt>a.is_cof</tt> and <tt>a.trigramme</tt> values.
+     */
     static prop_amount(a) {
         return amountDisplay(a.amount, a.is_cof, a.trigramme);
     }
 
+    /**
+     * <tt>addcost</tt> property is displayed iff <tt>a.addcost_for</tt> is nonempty.
+     */
     static prop_addcost(a) {
         if (a.addcost_for) {
             return '('+amountDisplay(a.addcost_amount, a.is_cof)
@@ -1466,6 +1581,9 @@ class OperationFormatter extends Formatter {
         }
     }
 
+    /**
+     * <tt>canceled</tt> property is displayed iff <tt>a.canceled_at</tt> is defined.
+     */
     static prop_canceled(a) {
         if (a.canceled_at) {
             cancel = 'Annulé';
@@ -1484,6 +1602,10 @@ class OperationFormatter extends Formatter {
     }
 }
 
+/**
+ * @extends Formatters.OperationFormatter
+ * @memberof Formatters
+ */
 class PurchaseFormatter extends OperationFormatter {
 
     static prop_infos1(a) {
@@ -1495,8 +1617,15 @@ class PurchaseFormatter extends OperationFormatter {
     }
 }
 
+/**
+ * @extends Formatters.OperationFormatter
+ * @memberof Formatters
+ */
 class SpecialOpeFormatter extends OperationFormatter {
     
+    /**
+     * <tt>a.amount</tt> with two decimal places.
+     */
     static prop_infos1(a) {
         return a.amount.toFixed(2)+'€';
     }
@@ -1524,8 +1653,15 @@ class SpecialOpeFormatter extends OperationFormatter {
     }
 }
 
+/**
+ * @extends Formatters.OperationFormatter
+ * @memberof Formatters
+ */
 class TransferFormatter extends OperationFormatter {
 
+    /**
+     * <tt>a.amount</tt> with two decimal places.
+     */
     static prop_amount(a) {
         return a.amount.toFixed(2)+'€';
     }