8000 update docs for handling plugin errors (#48) · ilesinge/jsdoc.github.io@7df4238 · GitHub
[go: up one dir, main page]
Skip to content

Commit 7df4238

Browse files
hegemonichegemonic
committed
update docs for handling plugin errors (jsdoc#48)
1 parent 85e5c65 commit 7df4238

File tree

2 files changed

+47
-12
lines changed

2 files changed

+47
-12
lines changed

‎about-plugins.html

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ <h2>Table of Contents</h2>
4040
<a href="#node-visitors">Node Visitors</a>
4141
</li>
4242
<li>
43-
<a href="#throwing-errors">Throwing Errors</a>
43+
<a href="#reporting-errors">Reporting Errors</a>
4444
</li>
4545
</ul>
4646
</li>
@@ -357,14 +357,31 @@ <h4 id="example-of-a-node-visitor">Example of a node visitor</h4>
357357
of doclets it knows about.</p>
358358
<p>Lastly, the visitors are executed in the order the plugins are listed in the conf.json file. A plugin can stop later plugins from visiting a node by setting
359359
a <code>stopPropagation</code> property on the event object (<code>e.stopPropagation = true</code>). A plugin can stop the event from firing by setting a <code>preventDefault</code> property.</p>
360-
<h3 id="throwing-errors">Throwing Errors</h3>
361-
<p>If you wish your plugin to throw an error, do it using the <code>handle</code> function in the <code>jsdoc/util/error</code> module.</p>
360+
<h3 id="reporting-errors">Reporting Errors</h3>
361+
<p>If your plugin needs to report an error, use one of the following methods in the <code>jsdoc/util/logger</code> module:
362+
</p>
363+
<ul>
364+
<li><code>logger.warn</code>: Warn the user about a possible problem.</li>
365+
<li><code>logger.error</code>: Report an error from which the plugin can recover.</li>
366+
<li><code>logger.fatal</code>: Report an error that should cause JSDoc to stop running.</li>
367+
</ul>
368+
<p>Using these methods creates a better user experience than simply throwing an error.</p>
369+
<p><strong>Note</strong>: Do not use the <code>jsdoc/util/error</code> module to report errors. This module is deprecated and will be removed in a future version
370+
of JSDoc.</p>
362371
<figure>
363-
<figcaption>Example</figcaption><pre class="prettyprint lang-js"><code>require('jsdoc/util/error').handle( new Error('I do not like green eggs and ham!') );
372+
<figcaption>Reporting a non-fatal error</figcaption><pre class="prettyprint lang-js"><code>var logger = require('jsdoc/util/logger');
373+
374+
exports.handlers = {
375+
newDoclet: function(e) {
376+
// ...
377+
378+
if (somethingBadHappened) {
379+
logger.error('Oh, no, something bad happened!');
380+
}
381+
}
382+
}
364383
</code></pre>
365384
</figure>
366-
<p>By default, this will throw the error, halting the execution of JSDoc. However, if the user enabled JSDoc&#39;s <code>--lenient</code> switch, JSDoc will simply
367-
log the error to the console and continue.</p>
368385
</article>
369386
<footer>
370387
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">

‎content/en/about-plugins.md

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -366,15 +366,33 @@ You'll notice a `finishers` property set. The finishers property should contain
366366

367367
Lastly, the visitors are executed in the order the plugins are listed in the conf.json file. A plugin can stop later plugins from visiting a node by setting a `stopPropagation` property on the event object (`e.stopPropagation = true`). A plugin can stop the event from firing by setting a `preventDefault` property.
368368

369-
### Throwing Errors
369+
### Reporting Errors
370370

371-
If you wish your plugin to throw an error, do it using the `handle` function in the `jsdoc/util/error` module.
371+
If your plugin needs to report an error, use one of the following methods in the `jsdoc/util/logger`
372+
module:
372373

373-
{% example "Example" %}
374+
+ `logger.warn`: Warn the user about a possible problem.
375+
+ `logger.error`: Report an error from which the plugin can recover.
376+
+ `logger.fatal`: Report an error that should cause JSDoc to stop running.
377+
378+
Using these methods creates a better user experience than simply throwing an error.
379+
380+
**Note**: Do not use the `jsdoc/util/error` module to report errors. This module is deprecated and
381+
will be removed in a future version of JSDoc.
382+
383+
{% example "Reporting a non-fatal error" %}
374384

375385
```js
376-
require('jsdoc/util/error').handle( new Error('I do not like green eggs and ham!') );
386+
var logger = require('jsdoc/util/logger');
387+
388+
exports.handlers = {
389+
newDoclet: function(e) {
390+
// Your code here.
391+
392+
if (somethingBadHappened) {
393+
logger.error('Oh, no, something bad happened!');
394+
}
395+
}
396+
}
377397
```
378398
{% endexample %}
379-
< 3DE0 /td>
380-
By default, this will throw the error, halting the execution of JSDoc. However, if the user enabled JSDoc's `--lenient` switch, JSDoc will simply log the error to the console and continue.

0 commit comments

Comments
 (0)
0