From 164b51f246268ffda58d27116a06d4cc26a4c674 Mon Sep 17 00:00:00 2001 From: The Jared Wilcurt Date: Sun, 11 Oct 2020 15:19:50 -0400 Subject: [PATCH 1/2] Put API in tables, add type information I had to dig into the source code to see what the types and defaults were for the API. This should be documented. I put the data into markdown tables, to make it easier to read. This is something I do for all of my own libraries. However if you don't like the tables, that's fine, but the data still needs to be displayed in some format in the docs. --- Readme.md | 42 ++++++++++++++++++++---------------------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/Readme.md b/Readme.md index 0db55e44..05885ef4 100644 --- a/Readme.md +++ b/Readme.md @@ -18,30 +18,27 @@ css.stringify(obj, options); ### css.parse(code, [options]) -Accepts a CSS string and returns an AST `object`. +Accepts a CSS string and returns an AST `object`. There are no required options. `options`: -- silent: silently fail on parse errors. -- source: the path to the file containing `css`. Makes errors and source - maps more helpful, by letting them know where code comes from. +**Key** | **Type** | **Default** | **Description** +:-- | :-- | :-- | :-- +`silent` | Boolean | `false` | Silently fail on parse errors if true. Throws if false. +`source` | String | `undefined` | Path to your CSS file. Makes errors and source maps more helpful, by letting them know where code comes from. ### css.stringify(object, [options]) -Accepts an AST `object` (as `css.parse` produces) and returns a CSS string. +Accepts an AST `object` (as `css.parse` produces) and returns a CSS string. There are no required options. `options`: -- indent: the string used to indent the output. Defaults to two spaces. -- compress: omit comments and extraneous whitespace. -- sourcemap: return a sourcemap along with the CSS output. Using the `source` - option of `css.parse` is strongly recommended when creating a source map. - Specify `sourcemap: 'generator'` to return the SourceMapGenerator object - instead of serializing the source map. -- inputSourcemaps: (enabled by default, specify `false` to disable) reads any - source maps referenced by the input files when generating the output source - map. When enabled, file system access may be required for reading the - referenced source maps. +**Key** | **Type** | **Default** | **Description** +:-- | :-- | :-- | :-- +`indent` | String | Two spaces | The string used to indent the output. +`compress` | Boolean | `false` | Omit comments and extraneous whitespace if true. +`sourcemap` | Boolean or String | `false` | Return a sourcemap along with the CSS output if true. Using the `source` option of `css.parse` is strongly recommended when creating a source map. Specify `sourcemap: 'generator'` to return the SourceMapGenerator object instead of serializing the source map. +`inputSourcemaps` | Boolean | `true` | Reads any source maps referenced by the input files when generating the output source map if true. File system access may be required for reading the referenced source maps if true. ### Example @@ -59,13 +56,14 @@ result.map // source map object Errors thrown during parsing have the following properties: -- message: `String`. The full error message with the source position. -- reason: `String`. The error message without position. -- filename: `String` or `undefined`. The value of `options.source` if - passed to `css.parse`. Otherwise `undefined`. -- line: `Integer`. -- column: `Integer`. -- source: `String`. The portion of code that couldn't be parsed. +**Key** | **Type** | **Description** +:-- | :-- | :-- +`message` | `String` | The full error message with the source position. +`reason` | `String` | The error message without position. +`filename` | `String` or `undefined` | The value of `options.source` if passed to `css.parse`. Otherwise `undefined`. +`line` | `Integer` | +`column` | `Integer` | +`source` | `String` | The portion of code that couldn't be parsed. When parsing with the `silent` option, errors are listed in the `parsingErrors` property of the [`stylesheet`](#stylesheet) node instead From 7ed10852f6d37898fb69604f531d722f76ebab8e Mon Sep 17 00:00:00 2001 From: The Jared Wilcurt Date: Sun, 11 Oct 2020 15:31:27 -0400 Subject: [PATCH 2/2] Update Readme.md --- Readme.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Readme.md b/Readme.md index 05885ef4..e8816486 100644 --- a/Readme.md +++ b/Readme.md @@ -22,10 +22,10 @@ Accepts a CSS string and returns an AST `object`. There are no required options. `options`: -**Key** | **Type** | **Default** | **Description** -:-- | :-- | :-- | :-- -`silent` | Boolean | `false` | Silently fail on parse errors if true. Throws if false. -`source` | String | `undefined` | Path to your CSS file. Makes errors and source maps more helpful, by letting them know where code comes from. +**Key** | **Type** | **Default** | **Description** +:-- | :-- | :-- | :-- +`silent` | `Boolean` | `false` | Silently fail on parse errors if true. Throws if false. +`source` | `String` | `undefined` | Path to your CSS file. Makes errors and source maps more helpful, by letting them know where code comes from. ### css.stringify(object, [options]) @@ -33,12 +33,12 @@ Accepts an AST `object` (as `css.parse` produces) and returns a CSS string. Ther `options`: -**Key** | **Type** | **Default** | **Description** -:-- | :-- | :-- | :-- -`indent` | String | Two spaces | The string used to indent the output. -`compress` | Boolean | `false` | Omit comments and extraneous whitespace if true. -`sourcemap` | Boolean or String | `false` | Return a sourcemap along with the CSS output if true. Using the `source` option of `css.parse` is strongly recommended when creating a source map. Specify `sourcemap: 'generator'` to return the SourceMapGenerator object instead of serializing the source map. -`inputSourcemaps` | Boolean | `true` | Reads any source maps referenced by the input files when generating the output source map if true. File system access may be required for reading the referenced source maps if true. +**Key** | **Type** | **Default** | **Description** +:-- | :-- | :-- | :-- +`indent` | `String` | Two spaces | The string used to indent the output. +`compress` | `Boolean` | `false` | Omit comments and extraneous whitespace if true. +`sourcemap` | `Boolean` or `String` | `false` | Return a sourcemap along with the CSS output if true. Using the `source` option of `css.parse` is strongly recommended when creating a source map. Specify `sourcemap: 'generator'` to return the SourceMapGenerator object instead of serializing the source map. +`inputSourcemaps` | `Boolean` | `true` | Reads any source maps referenced by the input files when generating the output source map if true. File system access may be required for reading the referenced source maps if true. ### Example