about-namepaths.html

<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">

<head>
  <meta charset="utf-8">
  <meta name="description" content="A guide to using namepaths with JSDoc 3.">
  <title>Use JSDoc: Using namepaths with JSDoc 3</title>
  <link rel="stylesheet" href="styles/usejsdoc.css">
  <link rel="stylesheet" href="styles/prettify.css">
  <link rel="stylesheet" href="styles/css3-github-ribbon.css">
  <script src="scripts/prettify.js"></script>
  <!--[if lt IE 9]>
            <script src="scripts/html5shiv.min.js"></script>
            <script src="scripts/html5shiv-printshiv.min.js"></script>
        <![endif]-->
</head>

<body>
  <header>
    <a href="./index.html">@use JSDoc</a>
  </header>
  <article>
    <h1>Using namepaths with JSDoc 3</h1>
    <h2>Table of Contents</h2>
    <ul>
      <li>
        <a href="#namepaths-in-jsdoc-3">Namepaths in JSDoc 3</a>
      </li>
      <li>
        <a href="#related-links">Related Links</a>
      </li>
    </ul>
    <h2 id="namepaths-in-jsdoc-3">Namepaths in JSDoc 3</h2>
    <p>When referring to a JavaScript variable that is elsewhere in your documentation, you must provide a unique identifier that maps to that variable. A namepath
      provides a way to do so and disambiguate between instance members, static members and inner variables.</p>
    <figure>
      <figcaption>Basic Syntax Examples of Namepaths in JSDoc 3</figcaption><pre class="prettyprint"><code>myFunction
MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash
</code></pre>
    </figure>
    <p>The example below shows: an <em>instance</em> method named &quot;say,&quot; an <em>inner</em> function also named &quot;say,&quot; and a <em>static</em> method
      also named &quot;say.&quot; These are three distinct methods that all exist independently of one another.</p>
    <figure>
      <figcaption>Use a documentation tag to describe your code.</figcaption><pre class="prettyprint lang-js"><code>/** @constructor */
Person = function() {
    this.say = function() {
        return "I'm an instance.";
    }

    function say() {
        return "I'm inner.";
    }
}
Person.say = function() {
    return "I'm static.";
}

var p = new Person();
p.say();      // I'm an instance.
Person.say(); // I'm static.
// there is no way to directly access the inner function from here
</code></pre>
    </figure>
    <p>You would use three different namepath syntaxes to refer to the three different methods:</p>
    <figure>
      <figcaption>Use a documentation tag to describe your code.</figcaption><pre class="prettyprint"><code>Person#say  // the instance method named "say."
Person.say  // the static method named "say."
Person~say  // the inner method named "say."
</code></pre>
    </figure>
    <p>You might wonder why there is a syntax to refer to an inner method when that method isn&#39;t directly accessible from outside the function it is defined in.
      While that is true, and thus the &quot;~&quot; syntax is rarely used, it <em>is</em> possible to return a reference to an inner method from another method
      inside that container, so it is possible that some object elsewhere in your code might borrow an inner method.</p>
    <p>Note that if a constructor has an instance member that is also a constructor, you can simply chain the namepaths together to form a longer namepath:</p>
    <figure>
      <figcaption>Use a documentation tag to describe your code.</figcaption><pre class="prettyprint lang-js"><code>/** @constructor */
Person = function() {
    /** @constructor */
    this.Idea = function() {
        this.consider = function(){
            return "hmmm";
        }
    }
}

var p = new Person();
var i = new p.Idea();
i.consider();
</code></pre>
    </figure>
    <p>In this case, to refer to the method named &quot;consider,&quot; you would use the following namepath:
      <code>Person#Idea#consider</code>
    </p>
    <p>This chaining can be used with any combination of the connecting symbols: <code># . ~</code>
    </p>
    <figure>
      <figcaption>Special cases: modules, externals and events.</figcaption><pre class="prettyprint lang-js"><code>/** A module. Its name is module:foo/bar.
 * @module foo/bar
 */
/** The built in string object. Its name is external:String.
 * @external String
 */
/** An event. Its name is module:foo/bar.event:MyEvent.
 * @event module:foo/bar.event:MyEvent
 */
</code></pre>
    </figure>
    <p>There are some special cases with namepaths: <a href="tags-module.html">@module</a> names are prefixed by &quot;module:&quot;, <a href="tags-external.html">@external</a>      names are prefixed by &quot;external:&quot;, and <a href="tags-event.html">@event</a> names are prefixed by &quot;event:&quot;.</p>
    <figure>
      <figcaption>Namepaths of objects with special characters in the name.</figcaption><pre class="prettyprint lang-js"><code>/** @namespace */
var chat = {
    /**
     * Refer to this by {@link chat."#channel"}.
     * @namespace
     */
    "#channel": {
        /**
         * Refer to this by {@link chat."#channel".open}.
         * @type {boolean}
         * @defaultvalue
         */
        open: true,
        /**
         * Internal quotes have to be escaped by backslash. This is
         * {@link chat."#channel"."say-\"hello\""}.
         */
        'say-"hello"': function (msg) {}
    }
};

/**
 * Now we define an event in our {@link chat."#channel"} namespace.
 * @event chat."#channel"."op:announce-motd"
 */
</code></pre>
    </figure>
    <p>Above is an example of a namespace with &quot;unusual&quot; characters in its member names (the hash character, dashes, even quotes). To refer to these you just
      need quote the names: chat.&quot;#channel&quot;, chat.&quot;#channel&quot;.&quot;op:announce-motd&quot;, and so on. Internal quotes in names should be escaped
      with backslashes: chat.&quot;#channel&quot;.&quot;say-\&quot;hello\&quot;&quot;.</p>
    <h2 id="related-links">Related Links</h2>
    <ul>
      <li>
        <a href="about-inline-tags.html">Inline tags</a>
      </li>
      <li>
        <a href="tags-link.html">@link</a>
      </li>
    </ul>
  </article>
  <footer>
    <a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
      <img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
    </a>
    <br> Copyright &#169; 2011-2014 the
    <a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
    <br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
        Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
  </footer>
  <script type="text/javascript">
    prettyPrint();
  </script>
</body>

</html>