### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Invalid JSDoc Comment Example Source: https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md This example shows an invalid JSDoc comment that will be ignored by documentation.js. JSDoc comments must start with /**, not //. This highlights the importance of correct JSDoc syntax. ```javascript // --- INVALID - this is ignored by JSDOC --- // This function adds one to its input. // @param {number} input any number // @returns {number} that number, plus one. ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Documenting a Simple JavaScript Function with JSDoc Source: https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md This snippet demonstrates how to document a basic JavaScript function using JSDoc syntax. It includes a description, parameter type and description, and return value description. Ensure the comment starts with /** for JSDoc to recognize it. ```javascript /** * This function adds one to its input. * @param {number} input any number * @returns {number} that number, plus one. */ function addOne(input) { return input + 1; } ``` -------------------------------- ### Untitled No description -------------------------------- ### Documenting Parameter with Union Type Source: https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md This JSDoc example shows how to document a parameter that accepts a specific set of string literal types using a union type. This provides more precise type checking for function inputs. ```javascript * @param {{status : "active" | "inactive" | "inprocess"}} ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Documenting a JavaScript Function with Flow Type Annotations Source: https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md This snippet demonstrates documenting a JavaScript function using Flow type annotations, offering a more compact syntax than traditional JSDoc for type declarations. The types are integrated directly into the function signature. ```javascript /** * This function adds one to its input. */ function addOne(input: number): number { return input + 1; } ``` -------------------------------- ### Install documentation.js Globally Source: https://github.com/documentationjs/documentation/blob/master/README.md This command installs the documentation.js CLI tool globally on your system using npm. This makes the `documentation` command available in your terminal for generating documentation from JSDoc-annotated source code. ```sh npm install -g documentation ``` -------------------------------- ### JavaScript Example for multilanguage.input Source: https://github.com/documentationjs/documentation/blob/master/__tests__/fixture/auto_lang_hljs/multilanguage.output.md This JavaScript code demonstrates how to instantiate and use the Foo class with the multilanguage.input function. It requires the Foo class to be defined and a data-foo attribute in the HTML. ```javascript var myFoo = new Foo('[data-foo]'); myFoo.foo(42); ``` -------------------------------- ### Documenting an Optional JavaScript Function Parameter Source: https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md This JSDoc snippet illustrates how to document an optional parameter in a JavaScript function. The square brackets `[]` around the parameter name indicate it's optional, and `=5` specifies a default value. ```javascript * @param {number} [input=5] any number ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Generate Markdown Documentation Source: https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md This example shows how to use the documentationjs library to build documentation from 'index.js' and format it as Markdown. The output is then written to './output.md'. It requires the 'documentation' and 'fs' modules. ```javascript var documentation = require('documentation'); var fs = require('fs'); documentation.build(['index.js']) .then(documentation.formats.md) .then(output => { // output is a string of Markdown data fs.writeFileSync('./output.md', output); }); ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Customizing Default Theme in documentation.yml Source: https://github.com/documentationjs/documentation/blob/master/docs/THEMING.md This example demonstrates how to make minor style adjustments to the default Documentation.js theme using a ### Sub Section header Text that describes the section and sub-section here. ``` -------------------------------- ### Untitled No description -------------------------------- ### Generate JSON Documentation Source: https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md This example demonstrates how to generate documentation from 'index.js' using documentationjs and format it as a JSON string. The resulting JSON data is saved to './output.json'. It depends on the 'documentation' and 'fs' modules. ```javascript var documentation = require('documentation'); var fs = require('fs'); documentation.build(['index.js']) .then(documentation.formats.json) .then(output => { // output is a string of JSON data fs.writeFileSync('./output.json', output); }); ``` -------------------------------- ### CSS Styling for multilanguage.input Source: https://github.com/documentationjs/documentation/blob/master/__tests__/fixture/auto_lang_hljs/multilanguage.output.md This CSS code applies a red background color to elements with the data-foo attribute, which is relevant to the multilanguage.input function's example. ```css [data-foo] { background-color: red; } ``` -------------------------------- ### Document JavaScript Promises with JSDoc Source: https://github.com/documentationjs/documentation/blob/master/docs/RECIPES.md This snippet demonstrates how to document a JavaScript function that returns a Promise. It uses JSDoc tags to specify the parameter types and the Promise's return type. The example shows a typical asynchronous operation that resolves with a string or rejects with an error. ```javascript /** * Find a person's phone number in the database * @param {string} name person's name * @returns {Promise} promise with the phone number */ function findPersonAge(name) { return new Promise((resolve, reject) => { db.find({ name: name }) .then(object => resolve(object.age)) .catch(err => reject(err)) }) } ``` -------------------------------- ### Use Custom Documentation.js Theme in Build Process Source: https://context7.com/documentationjs/documentation/llms.txt This JavaScript code snippet shows how to use a custom theme with documentation.js. It first builds the documentation comments from specified source files and then applies the custom HTML format, providing the path to the custom theme and project configuration. Finally, it writes the generated documentation files to the disk. Dependencies include 'documentation' and 'fs'. ```javascript // Use custom theme import documentation from 'documentation'; documentation.build(['src/index.js'], { access: ['public'], github: true }).then(comments => documentation.formats.html(comments, { theme: './custom-theme', projectName: 'My API', projectVersion: '1.0.0' }) ).then(output => { // Write output files output.forEach(file => { require('fs').writeFileSync(`docs/${file.path}`, file.contents); }); }); ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Basic documentation.yml Structure Source: https://github.com/documentationjs/documentation/blob/master/docs/CONFIG.md Illustrates a basic `documentation.yml` configuration for organizing API documentation entries and adding a narrative section with a description. ```yaml toc: - Map - name: Geography description: | These are Mapbox GL JS's ways of representing locations and areas on the sphere. - LngLat - LngLatBounds ``` -------------------------------- ### Specify Configuration File in Command Line Source: https://github.com/documentationjs/documentation/blob/master/docs/CONFIG.md Demonstrates how to use the `--config` option with the `documentation build` command to specify a custom configuration file. ```shell $ documentation build --config documentation.yml ... ``` -------------------------------- ### Untitled No description -------------------------------- ### Build HTML Docs with GitHub Links Source: https://github.com/documentationjs/documentation/blob/master/README.md This command builds HTML documentation for all files within the 'src' directory. It includes links to the source files on GitHub using the `--github` flag and outputs the documentation to the 'docs' directory using the `-o docs` flag. The `-f html` flag specifies the output format as HTML. ```sh documentation build src/** -f html --github -o docs ``` -------------------------------- ### Untitled No description -------------------------------- ### Build Documentation with CLI Source: https://context7.com/documentationjs/documentation/llms.txt Generate documentation from JavaScript source files using the command-line interface. Supports multiple output formats (markdown, HTML, JSON), GitHub integration, shallow mode, and TypeScript parsing. It can also document exported members and use watch mode for live updates. ```bash # Install globally npm install -g documentation # Generate markdown documentation from a single file documentation build index.js -f md > API.md # Generate HTML documentation with GitHub links documentation build src/** -f html --github -o docs # Generate JSON output for a file documentation build index.js -f json > docs.json # Build documentation for TypeScript files documentation build index.ts --parse-extension ts -f html -o docs # Build in shallow mode (no dependency resolution) documentation build index.js -f md --shallow # Document all exported members even without JSDoc documentation build --document-exported index.js -f html -o docs # Build with watch mode for live updates documentation build src/** -f html -o docs --watch # Filter by access level (public only) documentation build index.js -f md --access public ``` -------------------------------- ### Access Documentation.js Utility Functions for Custom Formatters Source: https://context7.com/documentationjs/documentation/llms.txt This JavaScript snippet demonstrates how to access and use utility functions from documentation.js, specifically for creating custom formatters. The `createFormatters` function allows for defining custom logic to format different parts of the documentation, enabling highly tailored output. It also shows how to initialize `LinkerStack` for managing links within custom themes. Dependencies include 'documentation'. ```javascript import documentation from 'documentation'; // Create formatters for custom output const formatters = documentation.util.createFormatters({ // Custom formatter configuration }); // Use LinkerStack for managing links in custom themes const LinkerStack = documentation.util.LinkerStack; const linkerStack = new LinkerStack({ /* configuration */ }); // Example: Custom formatter usage documentation.build(['index.js']).then(comments => { const customFormatters = documentation.util.createFormatters({ // Add custom type formatting }); // Use formatters in custom processing comments.forEach(comment => { if (comment.returns) { console.log(`${comment.name} returns: ${comment.returns[0].type}`); } }); }); ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Automated Release with npm Source: https://github.com/documentationjs/documentation/blob/master/CONTRIBUTING.md This snippet demonstrates how to initiate an automated release process for the documentation.js project using npm scripts. It covers both standard releases and pre-releases, updating the package version, creating a git tag, and preparing for publishing. ```bash # For a standard release: npm run release # For a pre-release (e.g., alpha): npm run release -- --prerelease alpha ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Use YAML Configuration with documentation.js CLI Source: https://context7.com/documentationjs/documentation/llms.txt Demonstrates how to use a YAML configuration file with the documentation.js command-line interface (CLI) to control the documentation build process. This enables organization, customization, and the application of specific configurations to generated documentation. ```bash # Use configuration file with CLI documentation build src/** -f html -o docs --config documentation.yml # Configuration affects the order and organization of output documentation build index.js -f md --config docs-config.yml > API.md ``` -------------------------------- ### Build Shallow Docs Source: https://github.com/documentationjs/documentation/blob/master/README.md This command generates Markdown documentation for 'index.js' but ignores any files that 'index.js' requires or imports. The `--shallow` flag limits the documentation generation to only the specified file, which can be useful for focusing on the direct exports of a module. ```sh documentation build index.js -f md --shallow ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Create Custom HTML Theme for Documentation Output Source: https://context7.com/documentationjs/documentation/llms.txt This snippet demonstrates how to create a custom HTML theme for documentation.js. It defines a function that accepts documentation comments and configuration, generates HTML content, and returns it as a Vinyl file object. This allows for full control over the generated documentation's appearance and structure. Dependencies include 'vinyl' and 'path'. ```javascript // custom-theme/index.js export default function customTheme(comments, config) { // comments: array of documentation objects // config: configuration options const Vinyl = require('vinyl'); const path = require('path'); // Generate custom HTML const html = ` ${config.projectName || 'Documentation'}

${config.projectName || 'API Documentation'}

${comments.map(comment => `

${comment.name}

${comment.description || ''}

`).join('')} `; // Return array of Vinyl file objects return Promise.resolve([ new Vinyl({ path: 'index.html', contents: Buffer.from(html) }) ]); } ``` -------------------------------- ### Build Markdown Docs Source: https://github.com/documentationjs/documentation/blob/master/README.md This command generates documentation in Markdown format for the specified JavaScript files and any files they reference. The `-f md` flag specifies the output format as Markdown. This is useful for creating documentation that can be easily integrated into README files or other Markdown-based project documentation. ```sh documentation build index.js -f md ``` -------------------------------- ### Build HTML Docs for TypeScript Source: https://github.com/documentationjs/documentation/blob/master/README.md This command builds HTML documentation for a TypeScript project. The `--parse-extension ts` flag tells documentation.js to parse TypeScript files, and `-f html` specifies the output format. The documentation is saved to the 'docs' directory. ```sh documentation build index.ts --parse-extension ts -f html -o docs ``` -------------------------------- ### Generate HTML Documentation with documentation.js API Source: https://context7.com/documentationjs/documentation/llms.txt Converts parsed documentation comments into HTML output using specified themes. It supports default themes and custom theme paths, along with options for access levels, GitHub integration, project metadata, and more. The output is an array of Vinyl file objects, which can then be written to the file system. Dependencies include 'documentation' and 'fs'. ```javascript import documentation from 'documentation'; // Generate HTML with default theme documentation.build(['index.js']) .then(comments => documentation.formats.html(comments, { theme: 'default_theme' })) .then(output => { // output is an array of Vinyl file objects output.forEach(file => { require('fs').writeFileSync(file.path, file.contents); }); }); // Use custom theme documentation.build(['src/index.js'], { access: ['public', 'protected'], github: true }).then(comments => documentation.formats.html(comments, { theme: './custom-theme', projectName: 'My Library', projectVersion: '2.0.0', projectDescription: 'A powerful JavaScript library', projectHomepage: 'https://example.com' }) ).then(output => { const fs = require('fs'); const path = require('path'); // Write HTML files to output directory output.forEach(file => { const outputPath = path.join('docs', file.relative); fs.mkdirSync(path.dirname(outputPath), { recursive: true }); fs.writeFileSync(outputPath, file.contents); }); console.log('HTML documentation generated successfully'); }) ``` -------------------------------- ### Generate Markdown Documentation Synchronously Source: https://github.com/documentationjs/documentation/blob/master/docs/USAGE_NODE.md This snippet demonstrates how to use documentation.js to synchronously parse inline source code and generate Markdown documentation. It takes an array of objects, each with a `source` and `file` property, as input. The output is a string containing the generated Markdown. Dependencies include the 'documentation' library itself. ```javascript var documentation = require('./'); var docs = documentation.buildSync([ { source: '/** hi this is a doc\n@name myDoc */', file: 'direct.js' } ]); documentation.formats.md(docs, {}, function(err, res) { console.log(res); }); ``` -------------------------------- ### Inject README Documentation with CLI Source: https://context7.com/documentationjs/documentation/llms.txt Automatically inject generated documentation into a README.md file or a custom markdown file under a specified section. Options include diff-only checks for CI, GitHub integration, and quiet mode. ```bash # Update API section in README.md documentation readme index.js --section=API # Inject into custom markdown file documentation readme src/index.js --section="API Reference" --readme-file=DOCS.md # Check if README needs updates (useful for CI) documentation readme index.js --section=API --diff-only # Inject with GitHub integration documentation readme index.js --section=API --github # Quiet mode (no console output) documentation readme index.js --section=API --quiet ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Make a sink - JavaScript Source: https://github.com/documentationjs/documentation/blob/master/__tests__/fixture/es6.output-toc.md This JavaScript method creates and returns an instance of the 'Sink' class. It accepts a single numeric argument, which is also documented as a linked type. The return value is explicitly linked to the 'Sink' class. ```javascript /** * This method returns a [sink](#sink). The type should be linked. * It takes a [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) which should also be linked. * * @param {Number} aNumber A number * @returns {[Sink](#sink)} a sink */ function makeASink(aNumber) {} ``` -------------------------------- ### Untitled No description -------------------------------- ### Lint Documentation with CLI Source: https://context7.com/documentationjs/documentation/llms.txt Check JSDoc comments for common style and uniformity mistakes using the command-line interface. Supports linting single or multiple files, custom inference of private members, and integration into CI/CD pipelines. ```bash # Lint a single file documentation lint util.js # Lint multiple files documentation lint src/**/*.js # Lint with custom inference of private members documentation lint index.js --infer-private '^_' # Use in CI/CD pipeline documentation lint src/** && echo "Documentation is valid" ``` -------------------------------- ### Untitled No description -------------------------------- ### Format documentation as HTML Source: https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md The `formats.html` function takes an array of parsed comments and configuration options to generate HTML output. It utilizes a theme to customize the appearance. This function is typically used after `documentation.build` to render the documentation in a web-friendly format. ```javascript var documentation = require('documentation'); documentation.build(['index.js']) .then(documentation.formats.html); ``` -------------------------------- ### Untitled No description -------------------------------- ### Build documentation from JavaScript files Source: https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md The `build` function generates documentation by parsing JSDoc comments from specified JavaScript files. It returns a Promise that resolves with an array of parsed comment objects, which can be used for further processing or rendering. It supports various options for controlling output, such as access levels, sorting order, and inferring private members. ```javascript var documentation = require('documentation'); documentation.build(['index.js'], { // only output comments with an explicit @public tag access: ['public'], sortOrder: ['kind', 'alpha'] }).then(res => { // res is an array of parsed comments with inferred properties // and more: everything you need to build documentation or // any other kind of code data. }); ``` -------------------------------- ### Untitled No description