8000 Pulled content for articles into extended_docs · seanpm2001/jsdoc.github.io@e26fff8 · GitHub
[go: up one dir, main page]
Skip to content

Commit e26fff8

Browse files
matthewkastormatthewkastor
committed
Pulled content for articles into extended_docs
For articles other than tags, I pulled their content to the Jake\extended_docs\ folders and put them into subfolders using their filename prefix. The contents of the files is included into the Jake\articles file so everything looks the same. The intent of this is to be able to map files into articles from various sources and maintain a single directory for user contributed files. As it stands, any files in the extended_docs folder would be hand written in HTML with the only special requirement being that code examples use the mustache example tag if they want to utilize whatever source highlighter we're using.
1 parent f7c4d3e commit e26fff8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+2262
-2099
lines changed

‎Jake/articles/about-getting-started

Lines changed: 8 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,11 @@
11
<!--{
2-
title: 'Getting Started with JSDoc 3',
3-
out: 'about-getting-started.html',
4-
description: 'A quick-start guide to automatically generating JavaScript documentation with JSDoc 3.'
2+
"title" : "Getting Started with JSDoc 3",
3+
"out" : "about-getting-started.html",
4+
"description" : "A quick-start guide to automatically generating JavaScript documentation with JSDoc 3."
55
}-->
66

7-
<h3>Getting Started</h3>
8-
9-
<p>
10-
JSDoc 3 is an API documentation generator for JavaScript, similar to JavaDoc or PHPDoc. You add documentation comments directly to your source code, right along side the code itself. The JSDoc Tool will scan your source code, and generate a complete HTML documentation website for you.
11-
</p>
12-
13-
<h3>Adding Documentation Comments to Your Code</h3>
14-
15-
<p>
16-
JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that you will want to document things like: namespaces, classes, methods, method parameters, etc.
17-
</p>
18-
19-
<p>
20-
JSDoc comments should generally be placed immediately before the code being documented. It must start with a <code>/**</code> sequence in order to be recognized by the JSDoc parser. Comments beginning with <code>/*</code>, <code>/***</code>, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks.
21-
</p>
22-
23-
{{#example}}The simplest documentation is just a description.
24-
/** This is a description of the foo function. */
25-
function foo() {
26-
}
27-
{{/example}}
28-
29-
<p>
30-
Adding a description is simple, just type the description you want in the documentaton comment.
31-
</p>
32-
33-
<p>
34-
Special "documentation tags" can be used to give more information. For example, if the function is a constructor, you can indicate this by adding a tag.
35-
</p>
36-
37-
{{#example}}Use a documentation tag to describe your code.
38-
/**
39-
Represents a book.
40-
@constructor
41-
*/
42-
function Book(title, author) {
43-
}
44-
{{/example}}
45-
46-
<p>
47-
More tags can be used to add more information. See the Tag Dictionary for a complete list of tags that are recognized by JSDoc 3.
48-
</p>
49-
50-
{{#example}}Adding more information with tags.
51-
/**
52-
Represents a book.
53-
@constructor
54-
@param {string} title - The title of the book.
55-
@param {string} author - The author of the book.
56-
*/
57-
function Book(title, author) {
58-
}
59-
{{/example}}
60-
61-
<h3>Generating A Website</h3>
62-
63-
<p>
64-
Once your code is commented, you can use the JSDoc 3 Tool to generate an HTML website from the source.
65-
</p>
66-
67-
<p>
68-
By default, JSDoc will use the "default" template to turn the documentation data into HTML. You can edit this template to suit your own needs, or create an entirely new template if that is what you prefer.
69-
</p>
70-
71-
{{#example}}Running the documentation generator on the command line.
72-
./jsdoc book.js
73-
{{/example}}
74-
75-
<p>
76-
This command will create a folder named "out" in the current working directory. Within that you will find the generated HTML pages.
77-
</p>
7+
<div class="about-overview" id="getting-started-overview">
8+
{{#include}}
9+
Jake/extended_docs/about/about-getting-started
10+
{{/include}}
11+
</div>

‎Jake/articles/about-including-readme

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,11 @@
11
<!--{
2-
title: 'Including a Readme File With JSDoc 3',
3-
out: 'about-including-readme.html',
4-
description: 'Using Readme files to add content to the default index.html.'
2+
"title" : "Including a Readme File With JSDoc 3",
3+
"out" : "about-including-readme.html",
4+
"description" : "Using Readme files to add content to the default index.html."
55
}-->
6-
<h3>Including a Readme File in Your Documentation With JSDoc 3</h3>
76

8-
<p>To include a readme file in your documentation, you simply specify the location of your readme file on the command line along with the location of your source files. The readme file will be incorporated into the index.html of your documentation in the default template. The file must be written in markdown and given a .md extension.</p>
9-
10-
{{#example}}Including a readme file in your documentation
11-
jsdoc C:\path\to\my\JS\project\sourceFiles C:\path\to\my\JS\project\README.md
12-
{{/example}}
13-
14-
<p>If your file is successfully incorporated into the default template, it's content will be rendered in beautiful HTML just before the files list.</p>
7+
<div class="about-overview" id="including-readme-overview">
8+
{{#include}}
9+
Jake/extended_docs/about/about-including-readme
10+
{{/include}}
11+
</div>

‎Jake/articles/about-jsdoc3

Lines changed: 8 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,11 @@
11
<!--{
2-
"title": "Readme",
3-
"out": "about-jsdoc3.html",
4-
"description": "Usage instructions and basic info about JSDoc 3"
2+
"title" : "Readme",
3+
"out" : "about-jsdoc3.html",
4+
"description" : "Usage instructions and basic info about JSDoc 3"
55
}-->
66

7-
<h1>
8-
JSDoc 3
9-
</h1>
10-
11-
<p>
12-
An inline API documentation processor for JavaScript. JSDoc 3 is intended to be an upgrade to JsDoc Toolkit (JSDoc 2).
13-
</p>
14-
15-
<h3>
16-
Pull Requesters: Please read HOW<em>TO</em>CONTRIBUTE.md
17-
</h3>
18-
19-
<h2>
20-
Installation
21-
</h2>
22-
23-
<p>
24-
Download a copy of JSDoc 3 from the official Git Hub repository here: <a href="https://github.com/jsdoc3/jsdoc">https://github.com/jsdoc3/jsdoc</a>
25-
</p>
26-
27-
<p>
28-
To test that jsdoc is working, change your working directory to the jsdoc folder and run the following command on Windows:
29-
</p>
30-
31-
{{#example}}Example
32-
jsdoc -T
33-
{{/example}}
34-
35-
<p>
36-
... or on a Max OSX or *nix platform:
37-
</p>
38-
39-
{{#example}}Example
40-
./jsdoc -T
41-
{{/example}}
42-
43-
<p>
44-
If you can't get the short-form commands to work, try invoking Java directly:
45-
</p>
46-
47-
{{#example}}Example
48-
java -cp lib/js.jar org.mozilla.javascript.tools.shell.Main \
49-
-modules nodejs_modules -modules rhino_modules -modules . \
50-
jsdoc.js -T
51-
{{/example}}
52-
53-
<h2>
54-
Usage
55-
</h2>
56-
57-
<p>
58-
This example assumes that your working directory is the jsdoc application base directory:
59-
</p>
60-
61-
62-
{{#example}}Example
63-
./jsdoc yourSourceCodeFile.js
64-
{{/example}}
65-
66-
<p>
67-
For help regarding the supported commandline options use the --help option.
68-
</p>
69-
70-
{{#example}}Example
71-
./jsdoc --help
72-
{{/example}}
73-
74-
<p>
75-
Generated documentation will appear in the folder specified by the --destination option, or in a folder named "out" by default.
76-
</p>
77-
78-
<h2>
79-
Dependencies
80-
</h2>
81-
82-
<p>
83-
JSDoc 3 utilises the Mozilla Rhino engine, which requires Java. JSDoc 3 is known to work with version 1.6.0_24 of Java.
84-
</p>
85-
86-
<p>
87-
JSDoc 3 uses advanced features in the Rhino application which are only available in or after the 1.7 release 3. A copy of this version of Rhino is included in JSDoc so this is not normally an issue that the user needs to be concerned with. However, in rare cases, users may have their Java CLASSPATH configured to override that included Rhino and point to some older version of Rhino instead. If this is the case, simply correct the CLASSPATH to remove the older Rhino.
88-
</p>
89-
90-
<p>
91-
The version of rhino distributed with JSDoc 3 can be found here: https://github.com/jannon/rhino
92-
</p>
93-
94-
<h2>
95-
Debugging
96-
</h2>
97-
98-
<p>
99-
Rhino is not always very friendly when it comes to reporting errors in JavaScript. Luckily it comes with a full-on debugger included that can be much more useful than a simple stack trace. To invoke JSDoc with the debugger try the following command:
100-
</p>
101-
102-
103-
{{#example}}Example
104-
jsdoc --debug
105-
{{/example}}
106-
107-
<p>
108-
or the long form version:
109-
</p>
110-
111-
{{#example}}Example
112-
$ java -classpath lib/js.jar \
113-
org.mozilla.javascript.tools.debugger.Main -debug \
114-
-modules nodejs_modules -modules rhino_modules -modules . \
115-
jsdoc.js \
116-
your/script.js
117-
{{/example}}
118-
119-
<p>
120-
Note: <code>--debug</code> must be the first argument to the short form command
121-
</p>
122-
123-
<p>
124-
This will open a debugging window. Choose "Break on Exceptions" from the "Debug" menu, then press the "Run" button. If there is an error, you should see exactly where it is in the source code.
125-
</p>
126-
127-
<h2>
128-
See Also
129-
</h2>
130-
131-
<p>
132-
<br>
133-
Project Documentation: <a href="http://usejsdoc.org/">http://usejsdoc.org/</a> (under development)
134-
<br>
135-
Project Documentation Source: <a href="https://github.com/micmath/micmath.github.com">https://github.com/micmath/micmath.github.com</a>
136-
<br>
137-
JSDoc User's Group: <a href="http://groups.google.com/group/jsdoc-users">http://groups.google.com/group/jsdoc-users</a>
138-
<br>
139-
JSDoc 3 Ant Task <a href="https://github.com/jannon/jsdoc3-ant-task">https://github.com/jannon/jsdoc3-ant-task</a>
140-
<br>
141-
Project Announcemnts: <a href="http://twitter.com/jsdoc3">http://twitter.com/jsdoc3</a>
142-
</p>
143-
144-
<h2>
145-
License
146-
</h2>
147-
148-
<p>
149-
JSDoc 3 is copyright (c) 2011 Michael Mathews <a href="mailto:micmath@gmail.com">micmath@gmail.com</a>
150-
</p>
151-
152-
<p>
153-
See file "LICENSE.md" in this distribution for more details about terms of use.
154-
</p>
7+
<div class="about-overview" id="jsdoc3-overview">
8+
{{#include}}
9+
Jake/extended_docs/about/about-jsdoc3
10+
{{/include}}
11+
</div>

0 commit comments

Comments
 (0)
0