From be9da2cfd1abc252a1fa1d9e13c59227188cc932 Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Tue, 22 Jan 2013 17:10:34 +1000 Subject: [PATCH 1/5] Added stub of inline tags page. --- Jake/articles/about-inline-tags | 49 +++++++++++++++++++++++++++++++++ Jake/articles/about-namepaths | 5 ++++ Jake/articles/index | 4 +++ 3 files changed, 58 insertions(+) create mode 100644 Jake/articles/about-inline-tags diff --git a/Jake/articles/about-inline-tags b/Jake/articles/about-inline-tags new file mode 100644 index 00000000..e93fe588 --- /dev/null +++ b/Jake/articles/about-inline-tags @@ -0,0 +1,49 @@ + +

Inline tags in JSDoc 3

+ +

+ Table of Contents +

+
    +
  1. Links to other symbols + +
      +
    1. @link +
      2. +
    2. @linkplain +
      3. +
    3. @linkmono +
      4. +
    4. Configuring link output +
      5. +
    +
    2. +
  2. Links to tutorials, @tutorial +
    3. +
  3. See also +
    4. +
+ +

+JSDoc has a number of inline tags. +These are different to its normal tags, because they can occur within the content of other tags. +The inline tags mainly provide ways to create links or cross-references to other parts of the documentation. +

+ + + +

@linkplain

+

@linkmono

+ + +

Links to other tutorials (@tutorial)

+ +

See Also

+ diff --git a/Jake/articles/about-namepaths b/Jake/articles/about-namepaths index 591d49bb..2ab8257f 100644 --- a/Jake/articles/about-namepaths +++ b/Jake/articles/about-namepaths @@ -82,3 +82,8 @@ In this case, to refer to the method named "consider," you would use the followi

This chaining can be used with any combination of the connecting symbols: # . ~

+ +

See Also

+ diff --git a/Jake/articles/index b/Jake/articles/index index 9f2b54d5..ae8ebcae 100644 --- a/Jake/articles/index +++ b/Jake/articles/index @@ -36,6 +36,8 @@
Additional longtext tutorials for your code.
Adding Content to Index.html
Using Readme files to add content to the default index.html
+
Linking.
+
All about inline tags @link, @linkplain, @linkcode, @tutorial.
All about plugins
Installing plugins and writing your own.
Configuring the markdown plugin
@@ -62,6 +64,8 @@

JSDoc 3 Tag Dictionary

+
Inline tags
+
All about inline tags {@link ...}, {@linkplain ...}, {@linkcode ...}, {@tutorial ...}.
{{#tagRefEntry}} {{tagRefEntry}} {{/tagRefEntry}} From 0ca802e7200a51e6c224165a13f8690b63720d4f Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Sat, 26 Jan 2013 13:27:17 +1000 Subject: [PATCH 2/5] added tags-link page for @link --- Jake/articles/tags-link | 137 ++++++++++++++++ tags-link.html | 334 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 471 insertions(+) create mode 100644 Jake/articles/tags-link create mode 100644 tags-link.html diff --git a/Jake/articles/tags-link b/Jake/articles/tags-link new file mode 100644 index 00000000..02069e1f --- /dev/null +++ b/Jake/articles/tags-link @@ -0,0 +1,137 @@ + +

Syntax

+ +{@link someSymbol}
+{@link http://some.url.com}
+[caption here]{@link someSymbol}
+[caption here]{@link http://some.url.com}
+{@link someSymbol|caption here}
+{@link http://some.url.com|caption here}
+{@link http://some.url.com Caption Here (after the first space)}
+{@link someSymbol Caption Here (after the first space)} + +

+The following work in the same way as @link but render in monospace or normal font respectively: +

+ +{@linkcode ...}
+{@linkplain ...} + + +

Overview

+

+The @link, @linkcode and @linkplain tags allow links to other documented objects or external URLs to be created within doclets (i.e., within the content of other tags). +

+ +

+You need to use a symbol's full name to have it linked (e.g. {@link MyNamespace.MyClass#property} rather than MyClass#property). +Also, remember that @modules, @externals and @events are prefixed by the tag name (e.g. "module:myModule"). +

+ +

The {@link ...} tag creates a (HTML) link in the generated output to the specified symbol or URL. +A link caption different to the link itself may be provided using the syntax specified above. +If the linked object doesn't exist, then the output is kept as text rather than turned into a link. +

+ +

+By default, {@link ...} just generates the HTML <a href="link URL">link text</code>. +It may be of interest to have link texts always rendered in monospace, particularly if it's a link to another code object. For example, you may want "{@link MY_CONSTANT}" to be rendered MY_CONSTANT rather than MY_CONSTANT. +

+ +

+To achieve this one can use @linkcode. It is exactly the same as @link, but renders the link caption in monospace. +For example, "{@linkcode fooBar}" turns into fooBar. +

+ +

+The @linkplain tag is opposite to @linkcode; it ensures that the link text is kept as-is, i.e. not turned into monospace. +

+ +

+If you want all @links to be rendered in monospace by default, you can set the templates.monospaceLinks option to true in your conf.json. +If you want @links to be rendered in normal text if they are links to external URLs (http, ftp) and in monospace otherwise, set the templates.cleverLinks option to true in your . +By default, all @links are rendered in normal font. +See the configuring JSDoc page for more information on setting these. +

+ + +

Examples

+ +{{#example}}Linking modules, externals and events. +/** A module. Refer to it using {@link module:foo/bar}. + * @module foo/bar + */ +/** The built in string object. Refer to it with {@link external:String}. + * @external String + */ +/** An event. Refer to with {@link module:foo/bar.event:MyEvent}. + * @event module:foo/bar.event:MyEvent + */ +{{/example}} + +{{#example}}Using @link +/** See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}. + * Also check out {@link http://www.google.com|google} and {@link http://github.com Github}. + */ +function myFunction() {} + +/** A class. + * @class */ +function MyClass() { + /** foo property */ + this.foo = 1; +} +{{/example}} + +

+The above produces (except that the first two links actually link to the generated documentation for MyClass and MyClass#foo): +

+See MyClass and MyClass's foo property. +Also check out google and Github. +
+

+ +{{#example}}Example with @linkplain and @linkcode +/** This is a variable {@link FOO}, cleverLinks makes this monospace. + * This is a link to external site {@link http://www.github.com|Github}, not monospace as it's external. + * This is a link to {@linkplain FOO}, but we forced it not to be monospace. + * This is a link to {@linkcode http://www.github.com Github}, but we forced it to be monospace. + * @const + */ +var FOO = 1; +{{/example}} + +

+With the default configuration, this would produce: +

+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace. +
+

+ +

+If templates.cleverLinks was on, it would produce: +

+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace. +
+

+ +

If template.monospaceLinks was on instead, all the links would be monospace except for the @linkplain. +

+ +

See Also

+ + diff --git a/tags-link.html b/tags-link.html new file mode 100644 index 00000000..fb896d9f --- /dev/null +++ b/tags-link.html @@ -0,0 +1,334 @@ + + + + + Use JSDoc: @link + + + + + + + + + + +
+ @use JSDoc +
+ + + +
+

@link

+ +

Syntax

+ +{@link someSymbol}
+{@link http://some.url.com}
+[caption here]{@link someSymbol}
+[caption here]{@link http://some.url.com}
+{@link someSymbol|caption here}
+{@link http://some.url.com|caption here}
+{@link http://some.url.com Caption Here (after the first space)}
+{@link someSymbol Caption Here (after the first space)} + +

+The following work in the same way as @link but render in monospace or normal font respectively: +

+ +{@linkcode ...}
+{@linkplain ...} + + +

Overview

+

+The @link, @linkcode and @linkplain tags allow links to other documented objects or external URLs to be created within doclets (i.e., within the content of other tags). +

+ +

+You need to use a symbol's full name to have it linked (e.g. {@link MyNamespace.MyClass#property} rather than MyClass#property). +Also, remember that @modules, @externals and @events are prefixed by the tag name (e.g. "module:myModule"). +

+ +

The {@link ...} tag creates a (HTML) link in the generated output to the specified symbol or URL. +A link caption different to the link itself may be provided using the syntax specified above. +If the linked object doesn't exist, then the output is kept as text rather than turned into a link. +

+ +

+By default, {@link ...} just generates the HTML <a href="link URL">link text</code>. +It may be of interest to have link texts always rendered in monospace, particularly if it's a link to another code object. For example, you may want "{@link MY_CONSTANT}" to be rendered MY_CONSTANT rather than MY_CONSTANT. +

+ +

+To achieve this one can use @linkcode. It is exactly the same as @link, but renders the link caption in monospace. +For example, "{@linkcode fooBar}" turns into fooBar. +

+ +

+The @linkplain tag is opposite to @linkcode; it ensures that the link text is kept as-is, i.e. not turned into monospace. +

+ +

+If you want all @links to be rendered in monospace by default, you can set the templates.monospaceLinks option to true in your conf.json. +If you want @links to be rendered in normal text if they are links to external URLs (http, ftp) and in monospace otherwise, set the templates.cleverLinks option to true in your . +By default, all @links are rendered in normal font. +See the configuring JSDoc page for more information on setting these. +

+ + +

Examples

+ +
+
Linking modules, externals and events.
+
+
+/** A module. Refer to it using {@link module:foo/bar}.
+ * @module foo/bar
+ */
+/** The built in string object. Refer to it with {@link external:String}.
+ * @external String
+ */
+/** An event. Refer to with {@link module:foo/bar.event:MyEvent}.
+ * @event module:foo/bar.event:MyEvent
+ */
+
+
+
+
+
Using @link
+
+
+/** See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
+ * Also check out {@link http://www.google.com|google} and {@link http://github.com Github}.
+ */
+function myFunction() {}
+
+/** A class.
+ * @class */
+function MyClass() {
+    /** foo property */
+    this.foo = 1;
+}
+
+
+
+

+The above produces (except that the first two links actually link to the generated documentation for MyClass and MyClass#foo): +

+See MyClass and MyClass's foo property. +Also check out google and Github. +
+

+ +
+
Example with @linkplain and @linkcode
+
+
+/** This is a variable {@link FOO}, cleverLinks makes this monospace.
+ * This is a link to external site {@link http://www.github.com|Github}, not monospace as it's external.
+ * This is a link to {@linkplain FOO}, but we forced it not to be monospace.
+ * This is a link to {@linkcode http://www.github.com Github}, but we forced it to be monospace.
+ * @const
+ */
+var FOO = 1;
+
+
+
+

+With the default configuration, this would produce: +

+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace. +
+

+ +

+If templates.cleverLinks was on, it would produce: +

+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace. +
+

+ +

If template.monospaceLinks was on instead, all the links would be monospace except for the @linkplain. +

+ +

See Also

+ + + +
+ + + + + + From 66801b5baf934a1c9ff9ac3011c15754a0fbe806 Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Sat, 26 Jan 2013 13:27:31 +1000 Subject: [PATCH 3/5] filled out tags-tutorial page for @tutorial --- Jake/articles/tags-tutorial | 35 ++++++++++++++++++++++++----- tags-tutorial.html | 44 +++++++++++++++++++++++++++++++------ 2 files changed, 66 insertions(+), 13 deletions(-) diff --git a/Jake/articles/tags-tutorial b/Jake/articles/tags-tutorial index 0b888ddd..d1ee7c72 100644 --- a/Jake/articles/tags-tutorial +++ b/Jake/articles/tags-tutorial @@ -3,22 +3,45 @@ "out": "tags-tutorial.html", "description": "Insert a link to an included tutorial file." }--> +

Syntax

+

As a block tag:

+@tutorial <tutorialID> + +

As an inline tag:

+{@tutorial <tutorialID>}

Overview

-

+

The @tutorial tag can be used both inline and as a normal tag. +It inserts a link to an included tutorial file. +See the tutorials tutorial for instructions on creating tutorials.

Examples

-

+{{#example}}Using @tutorial in a doclet. +/** Description + * @class + * @tutorial tutorial-1 + * @tutorial tutorial-2 + */ +function MyClass() {} +{{/example}} +

In the above example the MyClass documentation will have links to the tutorials identified by 'tutorial-1' and 'tutorial-2', a bit like the @see tag.

-{{#example}}Example goes here -// todo +{{#example}}Using @tutorial inline. +/** Description. + * Check out {@tutorial tutorial-1} and {@tutorial tutorial-2}. + * @class + */ +function MyClass() {} {{/example}} +

In its in-line usage the @tutorial tag is exactly like @link, but for tutorials.

See Also

\ No newline at end of file +
  • The tutorials tutorial
    • +
  • The @see tag, like @tutorial.
    • +
  • The @link tag, like {@tutorial} but for code objects or URLs.
    • + diff --git a/tags-tutorial.html b/tags-tutorial.html index f2b8f8c5..439d30cc 100644 --- a/tags-tutorial.html +++ b/tags-tutorial.html @@ -176,29 +176,59 @@

    @tutorial

    +

    Syntax

    +

    As a block tag:

    +@tutorial <tutorialID> + +

    As an inline tag:

    +{@tutorial <tutorialID>}

    Overview

    -

    +

    The @tutorial tag can be used both inline and as a normal tag. +It inserts a link to an included tutorial file. +See the tutorials tutorial for instructions on creating tutorials.

    Examples

    -

    +

    +
    Using @tutorial in a doclet.
    +
    +
    +/** Description
+ * @class
+ * @tutorial tutorial-1
+ * @tutorial tutorial-2
+ */
+function MyClass() {}
+
+
    +
    +

    In the above example the MyClass documentation will have links to the tutorials identified by 'tutorial-1' and 'tutorial-2', a bit like the @see tag.

    -
    Example goes here
    +
    Using @tutorial inline.
    -// todo
+/** Description.
+ * Check out {@tutorial tutorial-1} and {@tutorial tutorial-2}.
+ * @class
+ */
+function MyClass() {}
    -

    See Also

    +

    In its in-line usage the @tutorial tag is exactly like @link, but for tutorials.

    + +

    See Also

    +
  • The tutorials tutorial
    • +
  • The @see tag, like @tutorial.
    • +
  • The @link tag, like {@tutorial} but for code objects or URLs.
    • + +