/wiki/TagName.wiki

 1#summary @name
 2
 3== The @name Tag ==
 4
 5In most cases !JsDoc Toolkit can determine the namepath of an object for you. This is a great convenience because it allows you to shorten your documentation comments to just the minimum information you wish to add. However, when it isn't clear you can provide the namepath yourself by using the `@name` tag.
 6
 7Be warned though, by using the `@name` tag you are telling !JsDoc Toolkit to ignore the surrounding code and to treat your documentation comment in isolation. This can be a powerful technique because it allows you to write documentation for objects that are not visible in the code itself (or are obscure for some reason).
 8
 9=== Syntax ===
10
11{{{
12@name theNamepath
13}}}
14
15 * theNamepath - Required: the namepath you wish to use, ignoring the surrounding code.
16
17=== Example ===
18
19{{{
20/**
21 * @name hiliteSearchTerm
22 * @function
23 */
24eval("window.hiliteSearchTerm = function(term) {};")
25
26}}}
27
28Without the `@name` tag, the `hiliteSearchTerm` function would be invisible to !JsDoc Toolkit. That's because it never tries to run your code, and can't parse strings the way `eval` would.
29
30Note that the `@function` tag was also required, and in many cases the `@memberOf` tag would be needed as well. Essentially this technique requires that you explicitly document _all_ of the information about an object, and so can be very verbose. Luckily, most of the time, it isn't needed as !JsDoc Toolkit can determine all such information automatically for you.
31
32=== Warning ===
33
34As mentioned, using the `@name` tag essentially isolates your documentation comment from the code. This usually gives you the result you expect, because this tag is only ever required when !JsDoc Toolkit can't automatically find the necessary information in the code already.
35
36However, !JsDoc Toolkit can be run so that it documents uncommented objects (using the `-a` commandline option to run !JsDoc Toolkit). So when you use the `@name` tag in places where !JsDoc Toolkit _can_ determine the namepath of an object on its own there may be a conflict.
37
38{{{
39/** @name Foo */
40Bar = function() {
41}
42}}}
43
44In this case, if you use the `-a` option, you end up with _two_ objects in your documentation: the `Foo` object and the `Bar` function. That may be exactly what you intend, but you may be confused if you thought (incorrectly) that `@name` would force the Bar function to be treated as if it were named "Foo" -- it doesn't.
45
46=== See Also ===
47
48  * the [TagFunction @function] tag.
49  * the [TagMemberOf @memberOf] tag.
50