| // Type definitions for comment-parser |
| // Project: comment-parser |
| // Definitions by: Javier "Ciberman" Mora <https://github.com/jhm-ciberman/> |
| |
| declare namespace parse { |
| |
| /** |
| * In case you need to parse tags in a different way you can specify custom parsers here. |
| * Each parser function takes string left after previous parsers were applied and the data produced by them. |
| * It should return either `undefined` or the new object, where `source` is the consumed substring. |
| */ |
| export type Parser = (str: string, data: any) => { source: string, data: any }; |
| |
| /** |
| * Represents a parsed doc comment. |
| */ |
| export interface Comment { |
| /** |
| * A list of tags that are present in this doc comment. |
| */ |
| tags: Tag[]; |
| /** |
| * The starting line in the source code of this doc comment. |
| */ |
| line: number; |
| /** |
| * The description of this doc comment. Empty string if no description was specified. |
| */ |
| description: string; |
| /** |
| * The source of this doc comment, exactly as it appeared in the doc comment before parsing. |
| */ |
| source: string; |
| } |
| |
| /** |
| * Represents a parsed tag. A tag has the following format: |
| * > @tag {type} [name=default] description |
| */ |
| export interface Tag { |
| /** |
| * The tag's kind, eg `param` or `return`. |
| */ |
| tag: string; |
| /** |
| * The name of this tag, ie the first word after the tag. Empty string if no name was specified. |
| */ |
| name: string; |
| /** |
| * `true` if the tag is optional (tag name enclosed in brackets), `false` otherwise. |
| */ |
| optional: boolean; |
| /** |
| * The type declaration of this tag that is enclosed in curly braces. Empty string if no type was specified. |
| */ |
| type: string; |
| /** |
| * The description of this tag that comes after the name. Empty string if no description was specified. |
| */ |
| description: string; |
| /** |
| * The line number where this tag starts |
| */ |
| line: number; |
| /** |
| * The source of this tag, exactly as it appeared in the doc comment before parsing. |
| */ |
| source: string; |
| /** |
| * The default value for this tag. `undefined` in case no default value was specified. |
| */ |
| default?: string; |
| /** |
| * A list of errors that occurred during the parsing of this tag. `undefined` if not error occurred. |
| */ |
| errors? : string[]; |
| /** |
| * If `dotted_names` was set to `true`, a list of sub tags. `undefined` if `dotted_names` was set to `false` or if |
| * no sub tags exist. |
| */ |
| tags?: Tag[]; |
| } |
| |
| /** |
| * Options for parsing doc comments. |
| */ |
| export interface Options { |
| /** |
| * In case you need to parse tags in a different way you can specify custom parsers here. |
| * Each parser function takes string left after previous parsers were applied and the data produced by them. |
| * It should return either `undefined` or the new object, where `source` is the consumed substring. |
| * |
| * If you specify custom parsers, the default parsers are overwritten, but you can access them via the constant |
| * `PARSERS`. |
| */ |
| parsers: Parser[]; |
| /** |
| * By default dotted names like `name.subname.subsubname` will be expanded into nested sections, this can be |
| * prevented by passing `opts.dotted_names = false`. |
| */ |
| dotted_names: boolean; |
| /** |
| * Impacts behavior of joining non-asterisked multiline comments. Strings, |
| * non-zero numbers, or `true` will collapse newlines. Strings will |
| * additionally replace leading whitespace and `true` will replace with |
| * a single space. |
| */ |
| join: string | number | boolean; |
| /** |
| * `true` to trim whitespace at the start and end of each line, `false` otherwise. |
| */ |
| trim: boolean; |
| /** |
| * Return `true` to toggle fenced state; upon returning `true` the |
| * first time, will prevent subsequent lines from being interpreted as |
| * starting a new jsdoc tag until such time as the function returns |
| * `true` again to indicate that the state has toggled back; can also |
| * be simply set to a string or regular expression which will toggle |
| * state upon finding an odd number of matches within a line. |
| */ |
| fence: string | RegExp | ((source: string) => boolean); |
| } |
| |
| /** |
| * Options for turning a parsed doc comment back into a string. |
| */ |
| export interface StringifyOptions { |
| /** |
| * Indentation for each line. If a string is passed, that string is used verbatim to indent each line. If a number |
| * is passed, indents each line with that many whitespaces. |
| */ |
| indent: string | number; |
| } |
| |
| export interface Stringify { |
| /** |
| * One may also convert comment-parser JSON structures back into strings using this stringify method. |
| * |
| * This method accepts the JSON as its first argument and an optional options object with an indent property set to |
| * either a string or a number that will be used to determine the number of spaces of indent. The indent of the start |
| * of the doc block will be one space less than the indent of each line of asterisks for the sake of alignment as per |
| * usual practice. |
| * |
| * The stringify export delegates to the specialized methods `stringifyBlocks`, `stringifyBlock`, and |
| * `stringifyTag`, which are available on the stringify function object. |
| * @param comment A tag, comment or a list of comments to stringify. |
| * @param options Options to control how the comment or comments are stringified. |
| * @return The stringified doc comment(s). |
| */ |
| (comment: Tag | Comment | Comment[], options?: Partial<StringifyOptions>): string; |
| /** |
| * Similar to `stringify`, but only accepts a list of doc comments. |
| * @param comments A list of comments to stringify. |
| * @param options Options to control how the comments are stringified. |
| * @return The stringified doc comment(s). |
| */ |
| stringifyBlocks(comments: Comment[], options?: Partial<StringifyOptions>): string; |
| /** |
| * Similar to `stringify`, but only accepts a single doc comment. |
| * @param comment A comment to stringify. |
| * @param options Options to control how the comment is stringified. |
| * @return The stringified doc comment(s). |
| */ |
| stringifyBlock(comment: Comment, options?: Partial<StringifyOptions>): string; |
| /** |
| * Similar to `stringify`, but only accepts a single tag. |
| * @param tag A tag to stringify. |
| * @param options Options to control how the tag is stringified. |
| * @return The stringified doc comment(s). |
| */ |
| stringifyTag(tag: Tag, options?: Partial<StringifyOptions>): string; |
| } |
| |
| export const stringify: parse.Stringify; |
| |
| /** |
| * The default list of parsers that is used to parse comments. |
| */ |
| export const PARSERS: Record<"parse_tag" | "parse_type" | "parse_description" | "parse_name", Parser> |
| } |
| |
| /** |
| * The main method of this module which takes comment string and returns an array of objects with parsed data. |
| * It is not trying to detect relations between tags or somehow recognize their meaning. Any tag can be used, as long |
| * as it satisfies the format. |
| * @param str A string with doc comments and source code to parse. |
| * @param opts Options to control how the source string is parsed. |
| * @return The parsed list of doc comments. |
| */ |
| declare function parse(str: string, opts?: Partial<parse.Options>): parse.Comment[]; |
| |
| export = parse; |