ckeditor/ckeditor4-docs

Missing `see` tag in JSDuck output

msamsel opened this issue · 2 comments

msamsel commented

There is used customised tag detection for JSDuck including @see tag.
https://github.com/ckeditor/ckeditor-docs/blob/3bb3e15ef6074f30eaa1ed4c29d3a3ff541f8035/source/customs.rb#L32-L38
However produced JSON doesn't contain information about @see tag.
It could be nice to check what is going on and implement some improvements, which will allow on proper recognition of @see tag.

Examples for docs:

1. @see tag below @param

 /**
 * Adds CSS rules to be appended to the editor document.
 * This method is mostly used by plugins to add custom styles to the editor
 * document. For basic content styling the `contents.css` file should be
 * used instead.
 *
 * **Note:** This function should be called before the creation of editor instances.
 *
 *		// Add styles for all headings inside editable contents.
 *		CKEDITOR.addCss( '.cke_editable h1,.cke_editable h2,.cke_editable h3 { border-bottom: 1px dotted red }' );
 *
 * @param {String} css The style rules to be appended.
 * @see CKEDITOR.config#contentsCss
 */

{
    "tagname": "method",
    "name": "addCss",
    "autodetected": {
        "inheritdoc": true,
        "static": true,
        "private": true,
        "inheritable": true,
        "linenr": true,
        "chainable": true,
        "fires": true,
        "method_calls": true
    },
    "files": [
        {
            "filename": "/Users/msamsel/work/ckeditor-dev/core/ckeditor.js",
            "linenr": 110
        }
    ],
    "doc": "<p>Adds CSS rules to be appended to the editor document.\nThis method is mostly used by plugins to add custom styles to the editor\ndocument. For basic content styling the <code>contents.css</code> file should be\nused instead.</p>\n\n<p><strong>Note:</strong> This function should be called before the creation of editor instances.</p>\n\n<pre><code>// Add styles for all headings inside editable contents.\n<a href=\"#!/api/CKEDITOR-method-addCss\" rel=\"CKEDITOR-method-addCss\" class=\"docClass\">CKEDITOR.addCss</a>( '.cke_editable h1,.cke_editable h2,.cke_editable h3 { border-bottom: 1px dotted red }' );\n</code></pre>\n",
    "params": [
        {
            "tagname": "params",
            "type": "String",
            "name": "css",
            "doc": "<p>The style rules to be appended.\n<a href=\"#!/api/CKEDITOR.config-cfg-contentsCss\" rel=\"CKEDITOR.config-cfg-contentsCss\" class=\"docClass\">CKEDITOR.config.contentsCss</a></p>\n",
            "html_type": "String"
        }
    ],
    "inheritdoc": null,
    "static": null,
    "private": null,
    "inheritable": null,
    "linenr": null,
    "chainable": false,
    "fires": null,
    "method_calls": null,
    "id": "method-addCss",
    "owner": "CKEDITOR",
    "short_doc": "Adds CSS rules to be appended to the editor document. ..."
}

2. @see tag above @param

 /**
 * Adds CSS rules to be appended to the editor document.
 * This method is mostly used by plugins to add custom styles to the editor
 * document. For basic content styling the `contents.css` file should be
 * used instead.
 *
 * **Note:** This function should be called before the creation of editor instances.
 *
 *		// Add styles for all headings inside editable contents.
 *		CKEDITOR.addCss( '.cke_editable h1,.cke_editable h2,.cke_editable h3 { border-bottom: 1px dotted red }' );
 *
 * @see CKEDITOR.config#contentsCss
 * @param {String} css The style rules to be appended.
 */

{
    "tagname": "method",
    "name": "addCss",
    "autodetected": {
        "inheritdoc": true,
        "static": true,
        "private": true,
        "inheritable": true,
        "linenr": true,
        "chainable": true,
        "fires": true,
        "method_calls": true
    },
    "files": [
        {
            "filename": "/Users/msamsel/work/ckeditor-dev/core/ckeditor.js",
            "linenr": 110
        }
    ],
    "doc": "<p>Adds CSS rules to be appended to the editor document.\nThis method is mostly used by plugins to add custom styles to the editor\ndocument. For basic content styling the <code>contents.css</code> file should be\nused instead.</p>\n\n<p><strong>Note:</strong> This function should be called before the creation of editor instances.</p>\n\n<pre><code>// Add styles for all headings inside editable contents.\n<a href=\"#!/api/CKEDITOR-method-addCss\" rel=\"CKEDITOR-method-addCss\" class=\"docClass\">CKEDITOR.addCss</a>( '.cke_editable h1,.cke_editable h2,.cke_editable h3 { border-bottom: 1px dotted red }' );\n</code></pre>\n\n<p><a href=\"#!/api/CKEDITOR.config-cfg-contentsCss\" rel=\"CKEDITOR.config-cfg-contentsCss\" class=\"docClass\">CKEDITOR.config.contentsCss</a></p>\n",
    "params": [
        {
            "tagname": "params",
            "type": "String",
            "name": "css",
            "doc": "<p>The style rules to be appended.</p>\n",
            "html_type": "String"
        }
    ],
    "inheritdoc": null,
    "static": null,
    "private": null,
    "inheritable": null,
    "linenr": null,
    "chainable": false,
    "fires": null,
    "method_calls": null,
    "id": "method-addCss",
    "owner": "CKEDITOR",
    "short_doc": "Adds CSS rules to be appended to the editor document. ..."
}
msamsel commented

Might be related:
senchalabs/jsduck#558

Some implementation found in comments:
senchalabs/jsduck#558 (comment)