jsdoc / jsdoc/jsdoc

Strip quotes from quoted module names, like module:"core.lang"

Open
#490 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
15.5k
Forks
1.5k
Avg merge
10d 23h
Merged PRs (30d)
1

Description

I have some modules (AMD) with "." in their name (like "core.lang.js" in the example below).
I can see two options: put module name in quotes and do not do this.
If I skip quotes in @export (in core.lang.js) and in @type (in core.js) (see #1 in the code) then generated doc will contain:

  • Index: lang in Module, link leads to lang.html (ok)
  • module-core.html: lang :module:core.lang where link module:core.lang leads to module-core.html#lang (wrong!)

If I put quotes (see #2 in the code) then generated doc will contain:

  • Index: "core.lang" in Module (with quotes!) leads to _.html (wrong!)
  • module-core.html: lang :module:"core.lang" where link module:"core.lang" leads to _.html (wrong!)
  • .html is actually page for core.lang module, but obviously it should not be named ".html"

So none of cases (with and without quotes) works correctly.

core.lang.js:

define([], function () {
    /**
     * #1: @exports core.lang
     * #2: @exports "core.lang"
     */
    var lang = {
        /**
         * Defines a class
         * @returns {Function}
         */
        Class: function () {    }
    };
    return lang;
});

core.js:

define(["core.lang"], function (lang) {
    /**
     * @exports core
     */
    var core = {};

    /**
     * base language helpers
     * #1: @type module:core.lang
     * #2: @type module:"core.lang"
     */
    core.lang = lang;

    return core;
});

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue with the provided core.lang.js and core.js AMD examples, comparing quoted and unquoted @exports and @type values. Trace the module-name parsing and link-generation entry points; done means quoted names are stripped and the generated module page and links use core.lang rather than _.html.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.