acorn vs doctrine
Parsing JavaScript Code and Documentation for Tooling
Search packages..
acorndoctrineSimilar Packages:

Parsing JavaScript Code and Documentation for Tooling

acorn and doctrine are foundational utilities for building JavaScript development tools, but they target different layers of the source code. acorn is a JavaScript parser that converts executable code into an Abstract Syntax Tree (AST), enabling analysis of logic and structure. doctrine is a JSDoc parser that converts documentation comments into a structured format, allowing tools to understand types and intent. While acorn handles the code itself, doctrine handles the metadata attached to that code.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
acorn011,451565 kB142 months agoMIT
doctrine0460-08 years agoApache-2.0

Acorn vs Doctrine: Code Parsing vs Documentation Parsing

Both acorn and doctrine are foundational utilities for building JavaScript development tools, but they target different layers of the source code. acorn is a JavaScript parser that converts executable code into an Abstract Syntax Tree (AST), enabling analysis of logic and structure. doctrine is a JSDoc parser that converts documentation comments into a structured format, allowing tools to understand types and intent. While acorn handles the code itself, doctrine handles the metadata attached to that code.

📄 What They Parse: Executable Code vs. Comments

acorn reads actual JavaScript logic.

  • It understands variables, functions, loops, and classes.
  • It ignores comments by default unless configured otherwise.
// acorn: Parses JavaScript code
const acorn = require("acorn");
const ast = acorn.parse("const x = 10;", { ecmaVersion: 2020 });
// Returns an AST representing the variable declaration

doctrine reads JSDoc comment strings.

  • It understands tags like @param, @returns, and @example.
  • It ignores the actual JavaScript logic around the comment.
// doctrine: Parses JSDoc comments
const doctrine = require("doctrine");
const jsdoc = doctrine.parse("/** @param {string} name */", { unwrap: true });
// Returns an AST representing the documentation tags

🌳 Output Structure: ESTree vs. JSDoc AST

acorn produces an ESTree compatible AST.

  • Nodes represent syntax elements like Identifier or Literal.
  • Tools traverse this tree to find code patterns.
// acorn: AST node example
// { type: "VariableDeclaration", declarations: [{ ... }] }
console.log(ast.body[0].type); 
// Output: "VariableDeclaration"

doctrine produces a JSDoc specific AST.

  • Nodes represent documentation tags like Param or Return.
  • Tools traverse this tree to validate documentation.
// doctrine: AST tag example
// { tags: [ { title: "param", type: { ... } } ] }
console.log(jsdoc.tags[0].title); 
// Output: "param"

🛠️ Real-World Tooling: Using Them Together

acorn is used for logic analysis.

  • Linters use it to find unused variables or complex functions.
  • Bundlers use it to resolve dependencies.
// acorn: Checking for unused variables (conceptual)
traverse(ast, (node) => {
  if (node.type === "VariableDeclaration") {
    // Check usage logic here
  }
});

doctrine is used for documentation validation.

  • Linters use it to ensure functions have JSDoc types.
  • Generators use it to build documentation sites.
// doctrine: Validating JSDoc types (conceptual)
jsdoc.tags.forEach((tag) => {
  if (tag.title === "param" && !tag.type) {
    // Report missing type error
  }
});

🤝 Similarities: Shared Ground in Tooling

While they parse different content, both packages share core design goals for tool builders. Here are key overlaps:

1. ⚡ Fast and Lightweight

  • Both are designed to be fast dependencies for larger tools.
  • They avoid heavy runtime overhead.
// Both are required synchronously for build tools
const acorn = require("acorn");
const doctrine = require("doctrine");

2. 🔧 Configurable Parsing

  • Both accept options to change how they read input.
  • You can toggle features like strict mode or comment unwrapping.
// acorn: Options for ECMAScript version
acorn.parse(code, { ecmaVersion: 2020 });

// doctrine: Options for unwrapping comments
doctrine.parse(comment, { unwrap: true });

3. ✅ Standard Compliance

  • acorn follows the ESTree specification for JS ASTs.
  • doctrine follows common JSDoc tagging standards.
// Both produce predictable structures for interoperability
// acorn -> ESTree
// doctrine -> JSDoc AST

📊 Summary: Key Differences

Featureacorndoctrine
Input📄 JavaScript Code💬 JSDoc Comments
Output🌳 ESTree AST🏷️ JSDoc AST
Primary Use🛠️ Linting, Bundling📚 Documentation, Types
Understands🧠 Logic and Syntax📝 Intent and Types
Dependencies🔗 Often standalone🔗 Often paired with Acorn

💡 The Big Picture

acorn is the engine for understanding code structure. It is essential when you need to know what the code does. Use it for linters, bundlers, and code modifiers.

doctrine is the engine for understanding documentation. It is essential when you need to know what the code means. Use it for documentation generators and comment validators.

Final Thought: In many professional tooling setups, you will use both. acorn finds the function, and doctrine reads the comment above it. Together, they provide a complete picture of the source code.

How to Choose: acorn vs doctrine

  • acorn:

    Choose acorn when you need to analyze or transform actual JavaScript logic, such as building a linter rule that checks function complexity or a bundler that splits code. It is the standard for parsing ES6+ syntax into a structured tree that tools can traverse. This package is essential when your tool must understand variable declarations, function calls, or control flow.

  • doctrine:

    Choose doctrine when your tool needs to read and validate JSDoc comments, such as enforcing documentation standards or extracting type information for documentation generators. It is specifically designed to understand the tags and structure within comment blocks. This package is ideal when you need to verify that functions are documented correctly without analyzing the code logic itself.

Similar Npm Packages to acorn

acorn is a small, fast, and efficient JavaScript parser written in JavaScript. It is designed to parse ECMAScript (JavaScript) code and generate an Abstract Syntax Tree (AST) that can be used for various purposes, such as code analysis, transformation, or linting. Acorn is known for its speed and flexibility, making it a popular choice among developers who need a lightweight solution for parsing JavaScript.

While Acorn is a powerful tool, there are alternatives available that also serve the purpose of parsing JavaScript code. Here are a couple of notable alternatives:

  • esprima is another popular JavaScript parser that is known for its compliance with the ECMAScript specification. It generates a comprehensive AST and is often used in tools that require a deep understanding of JavaScript syntax. Esprima is particularly valued for its accuracy and adherence to the latest ECMAScript standards. If you need a parser that strictly follows the ECMAScript specification and provides detailed error reporting, Esprima is a solid choice.
  • typescript is primarily known as a superset of JavaScript that adds static typing to the language. However, it also includes a powerful parser that can analyze and transform JavaScript and TypeScript code. TypeScript's parser is particularly useful if you are working in a TypeScript environment or need to handle both TypeScript and JavaScript codebases. Its type-checking capabilities can help catch errors early in the development process, making it a great option for larger projects.

To see how Acorn compares with Esprima and TypeScript, check out the comparison: Comparing acorn vs esprima vs typescript.

Similar Npm Packages to doctrine

doctrine is a JavaScript library used for parsing and interpreting JSDoc comments. It provides a way to extract structured information from comments in JavaScript code, enabling developers to generate documentation or perform static analysis. By leveraging doctrine, developers can easily work with JSDoc annotations, making it a valuable tool for projects that rely on JSDoc for documentation purposes. While doctrine is a powerful option for parsing JSDoc comments, there are other libraries in the JavaScript ecosystem that serve related purposes. Here are a few alternatives:

  • acorn is a small, fast, and efficient JavaScript parser that can be used to parse JavaScript code into an Abstract Syntax Tree (AST). While it is not specifically designed for parsing JSDoc comments, it can be extended to analyze JavaScript code and extract comments, including JSDoc annotations. If you need a lightweight parser for JavaScript that can be customized for various needs, acorn is a great choice.
  • esprima is another popular JavaScript parser that produces an AST from JavaScript code. Like acorn, esprima is not specifically focused on JSDoc but can be used to analyze JavaScript code and extract comments. It is known for its compliance with the ECMAScript specification and is widely used in various tools and libraries. If you require a robust and standards-compliant parser for JavaScript, esprima is an excellent option.
  • jsdoc is a documentation generator for JavaScript that parses JSDoc comments and generates HTML documentation. While it is not a direct alternative to doctrine for parsing comments, it serves a similar purpose by working with JSDoc annotations to create comprehensive documentation for JavaScript projects. If your primary goal is to generate documentation from JSDoc comments, using jsdoc is the way to go.

To see how doctrine compares with acorn, esprima, and jsdoc, check out the comparison: Comparing acorn vs doctrine vs esprima vs jsdoc.

README for acorn

Acorn

A tiny, fast JavaScript parser written in JavaScript.

Community

Acorn is open source software released under an MIT license.

You are welcome to report bugs or create pull requests on github.

Installation

The easiest way to install acorn is from npm:

npm install acorn

Alternately, you can download the source and build acorn yourself:

git clone https://github.com/acornjs/acorn.git
cd acorn
npm install

Importing acorn

ESM as well as CommonJS is supported for all 3: acorn, acorn-walk and acorn-loose.

ESM example for acorn:

import * as acorn from "acorn"

CommonJS example for acorn:

let acorn = require("acorn")

ESM is preferred, as it allows better editor auto-completions by offering TypeScript support. For this reason, following examples will use ESM imports.

Interface

parse(input, options) is the main interface to the library. The input parameter is a string, options must be an object setting some of the options listed below. The return value will be an abstract syntax tree object as specified by the ESTree spec.

import * as acorn from "acorn"
console.log(acorn.parse("1 + 1", {ecmaVersion: 2020}))

When encountering a syntax error, the parser will raise a SyntaxError object with a meaningful message. The error object will have a pos property that indicates the string offset at which the error occurred, and a loc object that contains a {line, column} object referring to that same position.

Options are provided by in a second argument, which should be an object containing any of these fields (only ecmaVersion is required):

  • ecmaVersion: Indicates the ECMAScript version to parse. Can be a number, either in year (2022) or plain version number (6) form, or "latest" (the latest the library supports). This influences support for strict mode, the set of reserved words, and support for new syntax features.

    NOTE: Only 'stage 4' (finalized) ECMAScript features are being implemented by Acorn. Other proposed new features must be implemented through plugins.

  • sourceType: Indicate the mode the code should be parsed in. Can be either "script", "module" or "commonjs". This influences global strict mode and parsing of import and export declarations.

    NOTE: If set to "module", then static import / export syntax will be valid, even if ecmaVersion is less than 6. If set to "commonjs", it is the same as "script" except that the top-level scope behaves like a function.

  • strict: When set to true, enable strict parsing mode even if sourceType is "script".

  • onInsertedSemicolon: If given a callback, that callback will be called whenever a missing semicolon is inserted by the parser. The callback will be given the character offset of the point where the semicolon is inserted as argument, and if locations is on, also a {line, column} object representing this position.

  • onTrailingComma: Like onInsertedSemicolon, but for trailing commas.

  • allowReserved: If false, using a reserved word will generate an error. Defaults to true for ecmaVersion 3, false for higher versions. When given the value "never", reserved words and keywords can also not be used as property names (as in Internet Explorer's old parser).

  • allowReturnOutsideFunction: By default, a return statement at the top level raises an error. Set this to true to accept such code.

  • allowImportExportEverywhere: By default, import and export declarations can only appear at a program's top level. Setting this option to true allows them anywhere where a statement is allowed, and also allows import.meta expressions to appear in scripts (when sourceType is not "module").

  • allowAwaitOutsideFunction: If false, await expressions can only appear inside async functions. Defaults to true in modules for ecmaVersion 2022 and later, false for lower versions. Setting this option to true allows to have top-level await expressions. They are still not allowed in non-async functions, though. Setting this option to true is not allowed when sourceType: "commonjs".

  • allowSuperOutsideMethod: By default, super outside a method raises an error. Set this to true to accept such code.

  • allowHashBang: When this is enabled, if the code starts with the characters #! (as in a shellscript), the first line will be treated as a comment. Defaults to true when ecmaVersion >= 2023.

  • checkPrivateFields: By default, the parser will verify that private properties are only used in places where they are valid and have been declared. Set this to false to turn such checks off.

  • locations: When true, each node has a loc object attached with start and end subobjects, each of which contains the one-based line and zero-based column numbers in {line, column} form. Default is false.

  • startLocation: An optional {line, column} object to use for the start of the parse. This is mostly useful when using parseExpressionAt with locations: true, to prevent the parser from having to determine the line position at the start position.

  • onToken: If a function is passed for this option, each found token will be passed in same format as tokens returned from tokenizer().getToken().

    If array is passed, each found token is pushed to it.

    Note that you are not allowed to call the parser from the callback—that will corrupt its internal state.

  • onComment: If a function is passed for this option, whenever a comment is encountered the function will be called with the following parameters:

    • block: true if the comment is a block comment, false if it is a line comment.
    • text: The content of the comment.
    • start: Character offset of the start of the comment.
    • end: Character offset of the end of the comment.

    When the locations options is on, the {line, column} locations of the comment’s start and end are passed as two additional parameters.

    If array is passed for this option, each found comment is pushed to it as object in Esprima format:

    {
  "type": "Line" | "Block",
  "value": "comment text",
  "start": Number,
  "end": Number,
  // If `locations` option is on:
  "loc": {
    "start": {line: Number, column: Number}
    "end": {line: Number, column: Number}
  },
  // If `ranges` option is on:
  "range": [Number, Number]
}

    Note that you are not allowed to call the parser from the callback—that will corrupt its internal state.

  • ranges: Nodes have their start and end characters offsets recorded in start and end properties (directly on the node, rather than the loc object, which holds line/column data. To also add a semi-standardized range property holding a [start, end] array with the same numbers, set the ranges option to true.

  • program: It is possible to parse multiple files into a single AST by passing the tree produced by parsing the first file as the program option in subsequent parses. This will add the toplevel forms of the parsed file to the "Program" (top) node of an existing parse tree.

  • sourceFile: When the locations option is true, you can pass this option to add a source attribute in every node’s loc object. Note that the contents of this option are not examined or processed in any way; you are free to use whatever format you choose.

  • directSourceFile: Like sourceFile, but a sourceFile property will be added (regardless of the location option) directly to the nodes, rather than the loc object.

  • preserveParens: If this option is true, parenthesized expressions are represented by (non-standard) ParenthesizedExpression nodes that have a single expression property containing the expression inside parentheses.

parseExpressionAt(input, offset, options) will parse a single expression in a string, and return its AST. It will not complain if there is more of the string left after the expression.

tokenizer(input, options) returns an object with a getToken method that can be called repeatedly to get the next token, a {start, end, type, value} object (with added loc property when the locations option is enabled and range property when the ranges option is enabled). When the token's type is tokTypes.eof, you should stop calling the method, since it will keep returning that same token forever.

Note that tokenizing JavaScript without parsing it is, in modern versions of the language, not really possible due to the way syntax is overloaded in ways that can only be disambiguated by the parse context. This package applies a bunch of heuristics to try and do a reasonable job, but you are advised to use parse with the onToken option instead of this.

In ES6 environment, returned result can be used as any other protocol-compliant iterable:

for (let token of acorn.tokenizer(str)) {
  // iterate over the tokens
}

// transform code to array of tokens:
var tokens = [...acorn.tokenizer(str)]

tokTypes holds an object mapping names to the token type objects that end up in the type properties of tokens.

getLineInfo(input, offset) can be used to get a {line, column} object for a given program string and offset.

The Parser class

Instances of the Parser class contain all the state and logic that drives a parse. It has static methods parse, parseExpressionAt, and tokenizer that match the top-level functions by the same name.

When extending the parser with plugins, you need to call these methods on the extended version of the class. To extend a parser with plugins, you can use its static extend method.

var acorn = require("acorn")
var jsx = require("acorn-jsx")
var JSXParser = acorn.Parser.extend(jsx())
JSXParser.parse("foo(<bar/>)", {ecmaVersion: 2020})

The extend method takes any number of plugin values, and returns a new Parser class that includes the extra parser logic provided by the plugins.

Command line interface

The bin/acorn utility can be used to parse a file from the command line. It accepts as arguments its input file and the following options:

  • --ecma3|--ecma5|--ecma6|--ecma7|--ecma8|--ecma9|--ecma10: Sets the ECMAScript version to parse. Default is version 9.

  • --module: Sets the parsing mode to "module". Is set to "script" otherwise.

  • --locations: Attaches a "loc" object to each node with "start" and "end" subobjects, each of which contains the one-based line and zero-based column numbers in {line, column} form.

  • --allow-hash-bang: If the code starts with the characters #! (as in a shellscript), the first line will be treated as a comment.

  • --allow-await-outside-function: Allows top-level await expressions. See the allowAwaitOutsideFunction option for more information.

  • --compact: No whitespace is used in the AST output.

  • --silent: Do not output the AST, just return the exit status.

  • --help: Print the usage information and quit.

The utility spits out the syntax tree as JSON data.

Existing plugins

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. For more details, please refer to our Terms & Privacy.