[fixed] documentation tweaks

thealjey · Feb 5, 2017 · 2402d0e · 2402d0e
1 parent 38b5f13
commit 2402d0e
Show file tree

Hide file tree

Showing 12 changed files with 113 additions and 123 deletions.
diff --git a/src/Compiler.js b/src/Compiler.js
@@ -47,8 +47,6 @@ export class Compiler {
    * @method done
    * @param {string}   inPath   - the input path
    * @param {Function} callback - a callback function
-   * @example
-   * Compiler.done('/path/to/an/input/file', callback);
    */
   static done(inPath: string, callback: () => void) {
     log(green(++i, '. Compiled ', inPath));
@@ -66,8 +64,6 @@ export class Compiler {
    * @param {string}      outPath  - the output path
    * @param {ProgramData} data     - processed application code with source maps
    * @param {Function}    callback - a callback function
-   * @example
-   * Compiler.writeAndCallDone('/path/to/an/input/file', '/path/to/the/output/file', data, callback);
    */
   static writeAndCallDone(inPath: string, outPath: string, data: ProgramData, callback: () => void) {
     Compiler.fsWrite(outPath, data, () => {
@@ -85,8 +81,6 @@ export class Compiler {
    * @param {ProgramData} data     - the data to write
    * @param {Function}    callback - a callback function
    * @return {void}
-   * @example
-   * Compiler.fsWrite('/path/to/an/output/file', data, callback);
    */
   static fsWrite(path: string, data: ProgramData, callback: () => void) {
     if (!data.code) {
@@ -118,8 +112,6 @@ export class Compiler {
    * @method mkdir
    * @param {string}   path     - a path to a file
    * @param {Function} callback - a callback function
-   * @example
-   * Compiler.mkdir('/path/to/a/file', callback);
    */
   static mkdir(path: string, callback: () => void) {
     mkdirp(dirname(path), mkdirpErr => {
@@ -139,8 +131,6 @@ export class Compiler {
    * @param {ProgramData}         data     - the actual program data to gzip
    * @param {ProgramDataCallback} callback - a callback function
    * @return {void}
-   * @example
-   * Compiler.gzip(data, callback);
    */
   static gzip(data: ProgramData, callback: ProgramDataCallback) {
     if (!data.code) {
@@ -163,8 +153,6 @@ export class Compiler {
    * @method fsRead
    * @param {string}              path     - the input path
    * @param {ProgramDataCallback} callback - a callback function
-   * @example
-   * Compiler.fsRead('/path/to/an/output/file', callback);
    */
   fsRead(path: string, callback: ProgramDataCallback) {
     readFile(path, (scriptErr, scriptData) => {
@@ -202,8 +190,6 @@ export class Compiler {
    * @param {string}      outPath  - the output path
    * @param {ProgramData} data     - processed application code with source maps
    * @param {Function}    callback - a callback function
-   * @example
-   * compiler.save('/path/to/an/input/file', '/path/to/the/output/file', data, callback);
    */
   save(inPath: string, outPath: string, data: ProgramData, callback: () => void) {
     this.fsRead(outPath, oldData => {

diff --git a/src/DevServer.js b/src/DevServer.js
@@ -35,6 +35,7 @@ const LIVERELOAD_PORT = 35729,
  * @param {DevServerConfig} [options={}] - optional configuration
  * @see {@link http://webpack.github.io/docs/webpack-dev-server.html webpack-dev-server}
  * @see {@link http://gaearon.github.io/react-hot-loader/ React Hot Loader}
+ * @see {@link https://facebook.github.io/watchman/ Watchman}
  * @example
  * import {DevServer} from 'webcompiler';
  * // or - import {DevServer} from 'webcompiler/lib/DevServer';
@@ -114,8 +115,6 @@ export class DevServer {
    * @memberof DevServer
    * @instance
    * @method watchSASS
-   * @example
-   * server.watchSASS();
    */
   watchSASS() {
     const {style, contentBase} = this.options;
@@ -141,8 +140,6 @@ export class DevServer {
    * @memberof DevServer
    * @instance
    * @method watchJS
-   * @example
-   * server.watchJS();
    */
   watchJS() {
     const {port} = this.options,
@@ -161,13 +158,12 @@ export class DevServer {
   }
 
   /**
-   * Starts the Webpack development server, compiles SASS and starts watching for file changes
+   * Starts the Webpack development server, compiles SASS and starts watching for file changes (only if the `style`
+   * option was specified)
    *
    * @memberof DevServer
    * @instance
    * @method run
-   * @example
-   * server.run();
    */
   run() {
     this.watchJS();

diff --git a/src/Documentation.js b/src/Documentation.js
@@ -38,6 +38,8 @@ const cwd = process.cwd(),
  * // or - var Documentation = require('webcompiler/lib/Documentation').Documentation;
  *
  * const docs = new Documentation();
+ *
+ * docs.run();
  */
 export class Documentation {
 
@@ -64,11 +66,6 @@ export class Documentation {
    * @instance
    * @method run
    * @param {Function} [callback=function () {}] - a callback function
-   * @return {void}
-   * @example
-   * docs.run(() => {
-   *   // generated the API documentation
-   * });
    */
   run(callback: () => void = noop) {
     findBinary('jsdoc', (error, jsdoc: NativeProcess) => {

diff --git a/src/JS.js b/src/JS.js
@@ -11,7 +11,9 @@ import {join} from 'path';
 const defaultConfigFile = join(__dirname, '..', '.eslintrc.yaml');
 
 /**
- * JavaScript compilation tools
+ * JavaScript compilation tools.
+ *
+ * Wraps {@link JSCompiler} to add static analysis and linting. If you don't want that, use {@link JSCompiler} directly.
  *
  * @class JS
  * @param {boolean} [compress=true]                           - if true `Compiler#save` will gzip compress the data in
@@ -22,8 +24,21 @@ const defaultConfigFile = join(__dirname, '..', '.eslintrc.yaml');
  * // or - import {JS} from 'webcompiler/lib/JS';
  * // or - var JS = require('webcompiler').JS;
  * // or - var JS = require('webcompiler/lib/JS').JS;
+ * import {join} from 'path';
+ *
+ * const srcDir = join(__dirname, 'src'),
+ *   libDir = join(__dirname, 'lib');
  *
  * const js = new JS();
+ *
+ * // compile for the browser
+ * js.fe(join(srcDir, 'script.js'), join(libDir, 'script.js'));
+ *
+ * // compile for Node.js
+ * js.be(join(srcDir, 'script.js'), join(libDir, 'script.js'));
+ *
+ * // compile entire directories for Node.js (non-JavaScript files are simply copied over)
+ * js.be(srcDir, libDir);
  */
 export class JS {
 
@@ -32,6 +47,7 @@ export class JS {
    *
    * @member {JSCompiler} compiler
    * @memberof JS
+   * @private
    * @instance
    */
   compiler: JSCompiler;
@@ -60,10 +76,6 @@ export class JS {
    * @static
    * @method typecheck
    * @param {Function} callback - a callback function, invoked only when successfully typechecked
-   * @example
-   * JS.typecheck(() => {
-   *   // successfully typechecked
-   * });
    */
   static typecheck(callback: () => void) {
     findBinary('flow', (error, flow: NativeProcess) => {
@@ -90,10 +102,6 @@ export class JS {
    * @method lint
    * @param {Array<string>} paths    - an array of paths to files/directories to lint
    * @param {Function}      callback - a callback function, invoked only when successfully linted
-   * @example
-   * js.lint(['/path/to/the/input/file.js', '/lint/this/directory/too'], () => {
-   *   // successfully linted
-   * });
    */
   lint(paths: string[], callback: () => void) {
     this.linter.run(paths, linterErr => {
@@ -114,10 +122,6 @@ export class JS {
    * @param {string}        inPath    - the input file (will also be linted)
    * @param {Array<string>} lintPaths - an array of paths to files/directories to lint
    * @param {Function}      callback  - a callback function, invoked only when successfully validated
-   * @example
-   * js.validate('/path/to/the/input/file.js', ['/lint/this/directory/too'], () => {
-   *   // successfully validated
-   * });
    */
   validate(inPath: string, lintPaths: string[], callback: () => void) {
     JS.typecheck(() => {
@@ -126,20 +130,17 @@ export class JS {
   }
 
   /**
-   * Wraps {@link JSCompiler#be} to add static analysis and linting
+   * Wraps {@link JSCompiler#be} to add static analysis and linting.
+   *
+   * If `inPath` is a directory, `outPath` has to be also.
    *
    * @memberOf JS
    * @instance
    * @method be
-   * @param {string}        inPath                    - the input path
-   * @param {string}        outPath                   - the output path
+   * @param {string}        inPath                    - the input file/directory path
+   * @param {string}        outPath                   - the output file/directory path
    * @param {Array<string>} [lintPaths=[]]            - an array of paths to files/directories to lint
    * @param {Function}      [callback=function () {}] - a callback function
-   * @return {void}
-   * @example
-   * compiler.be('/path/to/the/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () => {
-   *   // the code has passed all the checks and has been compiled successfully
-   * });
    */
   be(inPath: string, outPath: string, lintPaths: string[] = [], callback: () => void = noop) {
     this.validate(inPath, lintPaths, () => {
@@ -153,15 +154,10 @@ export class JS {
    * @memberOf JS
    * @instance
    * @method fe
-   * @param {string}        inPath                    - the input path
-   * @param {string}        outPath                   - the output path
+   * @param {string}        inPath                    - the input file path
+   * @param {string}        outPath                   - the output file path
    * @param {Array<string>} [lintPaths=[]]            - an array of paths to files/directories to lint
    * @param {Function}      [callback=function () {}] - a callback function
-   * @return {void}
-   * @example
-   * compiler.fe('/path/to/the/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () => {
-   *   // the code has passed all the checks and has been compiled successfully
-   * });
    */
   fe(inPath: string, outPath: string, lintPaths: string[] = [], callback: () => void = noop) {
     this.validate(inPath, lintPaths, () => {

diff --git a/src/JSCompiler.js b/src/JSCompiler.js
@@ -24,8 +24,21 @@ const {yellow, red} = consoleStyles;
  * // or - import {JSCompiler} from 'webcompiler/lib/JSCompiler';
  * // or - var JSCompiler = require('webcompiler').JSCompiler;
  * // or - var JSCompiler = require('webcompiler/lib/JSCompiler').JSCompiler;
+ * import {join} from 'path';
+ *
+ * const srcDir = join(__dirname, 'src'),
+ *   libDir = join(__dirname, 'lib');
  *
  * const compiler = new JSCompiler();
+ *
+ * // compile for the browser
+ * compiler.fe(join(srcDir, 'script.js'), join(libDir, 'script.js'));
+ *
+ * // compile for Node.js
+ * compiler.be(join(srcDir, 'script.js'), join(libDir, 'script.js'));
+ *
+ * // compile entire directories for Node.js (non-JavaScript files are simply copied over)
+ * compiler.be(srcDir, libDir);
  */
 export class JSCompiler extends Compiler {
 
@@ -46,11 +59,9 @@ export class JSCompiler extends Compiler {
    * @instance
    * @private
    * @method beDir
-   * @param {string}   inPath   - the input path
-   * @param {string}   outPath  - the output path
+   * @param {string}   inPath   - the input directory path
+   * @param {string}   outPath  - the output directory path
    * @param {Function} callback - a callback function
-   * @example
-   * compiler.beDir('/path/to/an/input/directory', '/path/to/the/output/directory', callback);
    */
   beDir(inPath: string, outPath: string, callback: () => void) {
     readdir(inPath, (readdirErr, files) => {
@@ -70,11 +81,9 @@ export class JSCompiler extends Compiler {
    * @instance
    * @private
    * @method beFile
-   * @param {string}   inPath   - the input path
-   * @param {string}   outPath  - the output path
+   * @param {string}   inPath   - the input file path
+   * @param {string}   outPath  - the output file path
    * @param {Function} callback - a callback function
-   * @example
-   * compiler.beFile('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback);
    */
   beFile(inPath: string, outPath: string, callback: () => void) {
     ++this.processing;
@@ -93,11 +102,9 @@ export class JSCompiler extends Compiler {
    * @instance
    * @private
    * @method copyFile
-   * @param {string}   inPath   - the input path
-   * @param {string}   outPath  - the output path
+   * @param {string}   inPath   - the input file path
+   * @param {string}   outPath  - the output file path
    * @param {Function} callback - a callback function
-   * @example
-   * compiler.copyFile('/path/to/an/input/file', '/path/to/the/output/file', callback);
    */
   copyFile(inPath: string, outPath: string, callback: () => void) {
     ++this.processing;
@@ -115,11 +122,9 @@ export class JSCompiler extends Compiler {
    * @instance
    * @private
    * @method beTraverse
-   * @param {string}   inPath   - the input path
-   * @param {string}   outPath  - the output path
+   * @param {string}   inPath   - the input file/directory path
+   * @param {string}   outPath  - the output file/directory path
    * @param {Function} callback - a callback function
-   * @example
-   * compiler.beTraverse('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback);
    */
   beTraverse(inPath: string, outPath: string, callback: () => void) {
     stat(inPath, (statErr, stats) => {
@@ -139,15 +144,15 @@ export class JSCompiler extends Compiler {
   /**
    * Compiles a JavaScript file or a directory for the back end. Non-JavaScript files are simply copied over.
    *
+   * If `inPath` is a directory, `outPath` has to be also.
+   *
    * @memberOf JSCompiler
    * @instance
    * @method be
-   * @param {string}   inPath                    - the input path
-   * @param {string}   outPath                   - the output path
+   * @param {string}   inPath                    - the input file/directory path
+   * @param {string}   outPath                   - the output file/directory path
    * @param {Function} [callback=function () {}] - a callback function
    * @return {void}
-   * @example
-   * compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback);
    */
   be(inPath: string, outPath: string, callback: () => void = noop) {
     if (this.processing) {
@@ -167,11 +172,9 @@ export class JSCompiler extends Compiler {
    * @memberOf JSCompiler
    * @instance
    * @method fe
-   * @param {string}   inPath                    - the input path
-   * @param {string}   outPath                   - the output path
+   * @param {string}   inPath                    - the input file path
+   * @param {string}   outPath                   - the output file path
    * @param {Function} [callback=function () {}] - a callback function
-   * @example
-   * compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback);
    */
   fe(inPath: string, outPath: string, callback: () => void = noop) {
     const compiler = getCompiler(inPath, outPath);

diff --git a/src/JSLint.js b/src/JSLint.js
@@ -20,7 +20,6 @@ const defaultConfigFile = join(__dirname, '..', '.eslintrc.yaml');
  * // or - import {JSLint} from 'webcompiler/lib/JSLint';
  * // or - var JSLint = require('webcompiler').JSLint;
  * // or - var JSLint = require('webcompiler/lib/JSLint').JSLint;
- * import {join} from 'path';
  *
  * const linter = new JSLint();
  */
@@ -51,6 +50,7 @@ export class JSLint {
    * @param {Array<string>} paths    - an array of paths to files/directories to lint
    * @param {LintCallback}  callback - a callback function
    * @example
+   * import {join} from 'path';
    * import {logLintingErrors} from 'webcompiler';
    *
    * // lint "index.js" as well as the entire contents of the "src" directory

diff --git a/src/NativeProcess.js b/src/NativeProcess.js
@@ -127,8 +127,6 @@ export class NativeProcess {
    * @memberof NativeProcess
    * @instance
    * @method kill
-   * @example
-   * someEpensiveProcess.kill();
    */
   kill() {
     if (this.proc) {