Vector static functions JSDoc comment does not differ from non static method
ff6347 opened this issue · 1 comments
Hey all,
sorry for the radio silence lately. I've been pretty annoyed by my one mess with the basil2 site (build times, messy CSS, messy markup etc) and I'm trying to make a new start. I'm not ready yet to share some code but I'm currently looking into building the reference based on jsdoc (since documentation.js has gotten stale and the json produced is so verbose).
I noticed the following in our documentation:
The JSDoc comment for the Vector.… functions static or non static is the same. This creates duplicate entries which my new system does not allow.
Take a look at these JSON elements:
non static function (https://github.com/basiljs/basil.js/blob/master/basil.js#L5211):
{
"comment": "/**\n * @summary Calculates the dot product from this vector to another.\n * @description Calculates the dot product from this vector to another as `x`, `y`, and `z` components or full vector.\n *\n * @cat Math\n * @subcat Vector\n * @method Vector.dot\n *\n * @param {Vector|Number} v Either a full vector or an `x` component.\n * @param {Number} [y] The `y` component.\n * @param {Number} [z] The `z` component.\n * @return {Number} The dot product.\n */",
"meta": {
"filename": "basil.js",
"lineno": 6573,
"columnno": 4,
"path": "/Users/icke/Documents/basiljs/basiljs.github.io-next/tmp/basiljs",
"code": {}
},
"summary": "Calculates the dot product from this vector to another.",
"description": "Calculates the dot product from this vector to another as `x`, `y`, and `z` components or full vector.",
"tags": [
{
"originalTitle": "cat",
"title": "cat",
"text": "Math",
"value": "Math"
},
{
"originalTitle": "subcat",
"title": "subcat",
"text": "Vector",
"value": "Vector"
}
],
"kind": "function",
"name": "dot",
"params": [
{
"type": {
"names": [
"Vector",
"Number"
]
},
"description": "Either a full vector or an `x` component.",
"name": "v"
},
{
"type": {
"names": [
"Number"
]
},
"optional": true,
"description": "The `y` component.",
"name": "y"
},
{
"type": {
"names": [
"Number"
]
},
"optional": true,
"description": "The `z` component.",
"name": "z"
}
],
"returns": [
{
"type": {
"names": [
"Number"
]
},
"description": "The dot product."
}
],
"memberof": "Vector",
"longname": "Vector.dot",
"scope": "static",
"category": "Math",
"subcategory": "Vector"
},and the static one (https://github.com/basiljs/basil.js/blob/master/basil.js#L5028):
{
"comment": "/**\n * @summary Calculates the dot product of two vectors.\n * @description Static function. Calculates the dot product of two vectors. Is meant to be called \"static\" i.e. `Vector.dot(v1, v2);`\n *\n * @cat Math\n * @subcat Vector\n * @method Vector.dot\n *\n * @param {Vector} v1 The first vector.\n * @param {Vector} v2 The second vector.\n * @return {Number} The dot product.\n * @static\n */",
"meta": {
"filename": "basil.js",
"lineno": 6452,
"columnno": 2,
"path": "/Users/icke/Documents/basiljs/basiljs.github.io-next/tmp/basiljs",
"code": {}
},
"summary": "Calculates the dot product of two vectors.",
"description": "Static function. Calculates the dot product of two vectors. Is meant to be called \"static\" i.e. `Vector.dot(v1, v2);`",
"tags": [
{
"originalTitle": "cat",
"title": "cat",
"text": "Math",
"value": "Math"
},
{
"originalTitle": "subcat",
"title": "subcat",
"text": "Vector",
"value": "Vector"
}
],
"kind": "function",
"name": "dot",
"params": [
{
"type": {
"names": [
"Vector"
]
},
"description": "The first vector.",
"name": "v1"
},
{
"type": {
"names": [
"Vector"
]
},
"description": "The second vector.",
"name": "v2"
}
],
"returns": [
{
"type": {
"names": [
"Number"
]
},
"description": "The dot product."
}
],
"scope": "static",
"memberof": "Vector",
"longname": "Vector.dot",
"category": "Math",
"subcategory": "Vector"
}The only difference we have here is the description. This makes it hard to parse. I will try some things that allow us to differentiate these in a new branch.