jest-docblock
Advanced tools
Comparing version 21.3.0-beta.8 to 21.3.0-beta.9
{ | ||
"name": "jest-docblock", | ||
"version": "21.3.0-beta.8", | ||
"version": "21.3.0-beta.9", | ||
"repository": { | ||
@@ -5,0 +5,0 @@ "type": "git", |
# jest-docblock | ||
`jest-docblock` is a package that can extract and parse a specially-formatted comment called a "docblock" at the top of a file. | ||
`jest-docblock` is a package that can extract and parse a specially-formatted | ||
comment called a "docblock" at the top of a file. | ||
A docblock looks like this: | ||
```js | ||
@@ -13,2 +15,3 @@ /** | ||
Docblocks can contain pragmas, which are words prefixed by `@`: | ||
```js | ||
@@ -23,2 +26,3 @@ /** | ||
Pragmas can also take arguments: | ||
```js | ||
@@ -33,2 +37,3 @@ /** | ||
`jest-docblock` can: | ||
* extract the docblock from some code as a string | ||
@@ -39,2 +44,3 @@ * parse a docblock string's pragmas into an object | ||
## Installation | ||
```sh | ||
@@ -64,3 +70,9 @@ # with yarn | ||
const { extract, strip, parse, parseWithComments, print } = require("jest-docblock"); | ||
const { | ||
extract, | ||
strip, | ||
parse, | ||
parseWithComments, | ||
print, | ||
} = require('jest-docblock'); | ||
@@ -79,3 +91,3 @@ const docblock = extract(code); | ||
console.log(print({pragmas, comments: "hi!"})) // /**\n * hi!\n *\n * @everything is:awesome\n * @flow\n */; | ||
console.log(print({pragmas, comments: 'hi!'})); // /**\n * hi!\n *\n * @everything is:awesome\n * @flow\n */; | ||
``` | ||
@@ -86,14 +98,25 @@ | ||
### `extract(contents: string): string` | ||
Extracts a docblock from some file contents. Returns the docblock contained in `contents`. If `contents` did not contain a docblock, it will return the empty string (`""`). | ||
Extracts a docblock from some file contents. Returns the docblock contained in | ||
`contents`. If `contents` did not contain a docblock, it will return the empty | ||
string (`""`). | ||
### `strip(contents: string): string` | ||
Strips the top docblock from a file and return the result. If a file does not have a docblock at the top, then return the file unchanged. | ||
Strips the top docblock from a file and return the result. If a file does not | ||
have a docblock at the top, then return the file unchanged. | ||
### `parse(docblock: string): {[key: string]: string}` | ||
Parses the pragmas in a docblock string into an object whose keys are the pragma tags and whose values are the arguments to those pragmas. | ||
Parses the pragmas in a docblock string into an object whose keys are the pragma | ||
tags and whose values are the arguments to those pragmas. | ||
### `parseWithComments(docblock: string): { comments: string, pragmas: {[key: string]: string} }` | ||
Similar to `parse` except this method also returns the comments from the docblock. Useful when used with `print()`. | ||
Similar to `parse` except this method also returns the comments from the | ||
docblock. Useful when used with `print()`. | ||
### `print({ comments?: string, pragmas?: {[key: string]: string} }): string` | ||
Prints an object of key-value pairs back into a docblock. If `comments` are provided, they will be positioned on the top of the docblock. | ||
Prints an object of key-value pairs back into a docblock. If `comments` are | ||
provided, they will be positioned on the top of the docblock. |
116
8515
3