From b0b1fdf936a7b14fb71bf63d0fac4427d8cad6ba Mon Sep 17 00:00:00 2001 From: Ludovic Stephan Date: Fri, 17 Mar 2017 21:00:58 -0300 Subject: [PATCH] Add jsdoc comments to history models --- kfet/static/kfet/js/kfet.api.js | 194 +++++++++++++++++++++++++++----- 1 file changed, 165 insertions(+), 29 deletions(-) diff --git a/kfet/static/kfet/js/kfet.api.js b/kfet/static/kfet/js/kfet.api.js index 1d99aaae..c90d864d 100644 --- a/kfet/static/kfet/js/kfet.api.js +++ b/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}. + *
+ * 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 - * @see {@link Models.TreeNode.compare|TreeNode.compare} + * Compares two ModelObject instances. */ 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 'day' - * @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 ['id', 'at', 'comment', 'valid_by'] + * @see {@link Models.ModelObject.props|ModelObject.props} + */ static get props() { return ['id', 'at', 'comment', 'valid_by']; } + /** + * Default values for HistoryGroup model instances + * @default { 'id': 0, 'at': moment(), 'comment': '', + 'valid_by': '' } + * @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 ['id', 'amount', 'at', 'is_cof', - * 'comment', 'trigramme', 'valid_by', 'day', 'type'] + * @default {@link Models.HistoryGroup.props|HistoryGroup.props} + ['is_cof', 'trigramme'] * @see {@link Models.ModelObject.props|ModelObject.props} */ static get props() { @@ -649,8 +663,8 @@ class OperationGroup extends HistoryGroup { /** * Default values for OperationGroup instances. - * @default {'id': 0, 'amount': 0, 'at': moment(), 'is_cof': false, - 'comment': '', 'trigramme': '', 'valid_by': ''} + * @default {@link Models.HistoryGroup.default_data|HistoryGroup.default_data} + + * {'amount': 0, 'is_cof': false, 'trigramme': ''} * @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 ['id', 'type', 'amount', 'article_name', 'article_nb', - * 'is_checkout', 'addcost_amount', 'addcost_for', 'canceled_at', - * 'canceled_by', 'from_acc', 'to_acc', 'opegroup'] + * @default ['id', 'amount', 'canceled_at', 'canceled_by'] * @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 {'id': 0, 'type': '', 'amount': 0, 'article_name': '', - * 'article_nb': 0, 'is_checkout': false, 'addcost_amount': 0, - * 'addcost_for': '', 'canceled_at': undefined, 'canceled_by': ''} + * @default {'id': '', 'amount': 0, 'canceled_at': undefined, 'canceled_by': '' } * @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 {@link Models.Operation.props|Operation.props} + ['article_name', 'article_nb', + * 'addcost_amount', 'addcost_for'] + * @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 {@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 {@link Models.Operation.props|Operation.props} + ['type', 'is_checkout'] + * @see {@link Models.ModelObject.props|ModelObject.props} + */ static get props() { return Operation.props.concat(['type', 'is_checkout']); } + /** + * Default values for SpecialOperation model instances + * @default {@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 {@link Models.Operation.props|Operation.props} + ['from_acc', 'to_acc'] + * @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 {@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; } + /** + * s.price 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; } - else if (a.stock >= -5) { return this._data_stock.low; } - else /* a.stock < -5 */ { return this._data_stock.neg; } + /** + * Value of data_stock attribute based on s.stock. + */ + 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 { + /** + * a.time formatted as HH:mm:ss + */ static prop_time(a) { return a.at.format('HH:mm:ss'); } + /** + * valid_by property is displayed only if a.valid_by 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} + ['infos', 'time'] + */ 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} + ['time'] + */ static get props() { return OperationGroup.props.concat(['time']); } + /** + * a.amount displayed according to a.is_cof and a.trigramme 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; } + /** + * a.date formatted as D MMMM + */ 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 ['amount', 'infos1', 'infos2', 'addcost', 'canceled'] + */ static get props() { return ['amount', 'infos1', 'infos2', 'addcost', 'canceled']; } @@ -1453,10 +1562,16 @@ class OperationFormatter extends Formatter { return ['canceled']; } + /** + * a.amount displayed according to a.is_cof and a.trigramme values. + */ static prop_amount(a) { return amountDisplay(a.amount, a.is_cof, a.trigramme); } + /** + * addcost property is displayed iff a.addcost_for 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 { } } + /** + * canceled property is displayed iff a.canceled_at 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 { + /** + * a.amount 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 { + /** + * a.amount with two decimal places. + */ static prop_amount(a) { return a.amount.toFixed(2)+'€'; }