Security News
JavaScript Leaders Demand Oracle Release the JavaScript Trademark
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
@microsoft/tsdoc
Advanced tools
@microsoft/tsdoc is a library for parsing and analyzing TypeScript doc comments. It provides a standardized way to document TypeScript code, enabling developers to create consistent and comprehensive documentation for their projects.
Parsing TSDoc Comments
This feature allows you to parse TSDoc comments from a string. The parser processes the comment and provides a structured representation of its content, which can be used for further analysis or documentation generation.
const tsdoc = require('@microsoft/tsdoc');
const parser = new tsdoc.TSDocParser();
const text = `/**
* This is a summary.
*
* @remarks
* Additional details go here.
*
* @param paramName - Description of the parameter.
* @returns Description of the return value.
*/`;
const parserContext = parser.parseString(text);
console.log(parserContext.docComment.summarySection.toString());
Custom TSDoc Tags
This feature allows you to define and use custom TSDoc tags. By extending the TSDoc configuration, you can introduce new tags that suit your project's specific documentation needs.
const tsdoc = require('@microsoft/tsdoc');
const configuration = new tsdoc.TSDocConfiguration();
configuration.addTagDefinition(new tsdoc.TSDocTagDefinition({
tagName: '@customTag',
syntaxKind: tsdoc.TSDocTagSyntaxKind.BlockTag
}));
const parser = new tsdoc.TSDocParser(configuration);
const text = `/**
* This is a summary.
*
* @customTag
* Custom tag content.
*/`;
const parserContext = parser.parseString(text);
console.log(parserContext.docComment.customBlocks[0].blockTag.tagName);
Validation of TSDoc Comments
This feature allows you to validate TSDoc comments and identify any issues or inconsistencies. The parser logs messages that can be reviewed to ensure the documentation adheres to the expected standards.
const tsdoc = require('@microsoft/tsdoc');
const parser = new tsdoc.TSDocParser();
const text = `/**
* This is a summary.
*
* @param paramName - Description of the parameter.
* @returns Description of the return value.
*/`;
const parserContext = parser.parseString(text);
const messages = parserContext.log.messages;
messages.forEach(message => {
console.log(`${message.messageId}: ${message.text}`);
});
TypeDoc is a documentation generator for TypeScript projects. It generates HTML documentation from TypeScript source files, leveraging TypeScript's type system to provide detailed and accurate documentation. Unlike @microsoft/tsdoc, which focuses on parsing and analyzing doc comments, TypeDoc is more about generating complete documentation websites.
JSDoc is a popular documentation generator for JavaScript and TypeScript. It uses special comments to generate HTML documentation. While JSDoc is more mature and widely used, it does not provide the same level of TypeScript-specific features and integration as @microsoft/tsdoc.
Documentation.js is a documentation generator for JavaScript and TypeScript. It supports various output formats, including HTML and Markdown. Similar to JSDoc, it focuses on generating documentation from comments but lacks the TypeScript-specific features provided by @microsoft/tsdoc.
This library is the reference implementation of a parser for the TSDoc syntax. Using this library is an easy way to ensure that your tool is 100% compatible with the standard.
TSDoc is a proposal to standardize the doc comments used in TypeScript source files. It allows different tools to extract content from comments without getting confused by each other's syntax. The TSDoc notation looks pretty familiar:
export class Statistics {
/**
* Returns the average of two numbers.
*
* @remarks
* This method is part of the {@link core-library#Statistics | Statistics subsystem}.
*
* @param x - The first input number
* @param y - The second input number
* @returns The arithmetic mean of `x` and `y`
*
* @beta
*/
public static getAverage(x: number, y: number): number {
return (x + y) / 2.0;
}
}
Check out the TSDoc Playground for a cool live demo of our parser!
The api-demo folder on GitHub illustrates how to invoke the TSDoc parser.
A separate NPM package @microsoft/tsdoc-config
is used for loading the tsdoc.json file.
The TSDoc project is actively evolving. Please visit the website for the latest documentation, instructions for building/debugging the projects, and other resources:
FAQs
A parser for the TypeScript doc comment syntax
The npm package @microsoft/tsdoc receives a total of 2,797,421 weekly downloads. As such, @microsoft/tsdoc popularity was classified as popular.
We found that @microsoft/tsdoc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
Security News
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
Security News
Floating dependency ranges in npm can introduce instability and security risks into your project by allowing unverified or incompatible versions to be installed automatically, leading to unpredictable behavior and potential conflicts.