Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

escape-html: set up autogenerated API docs #14268

Merged
merged 3 commits into from
Mar 6, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions bin/update-readmes.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,34 @@ const path = require( 'path' );
const childProcess = require( 'child_process' );

const packages = [
//'a11y',
//'autop',
//'blob',
//'block-editor',
//'block-library',
//'block-serialization-default-parser',
//'blocks',
//'compose',
//'data',
//'date',
//'deprecated',
//'dom',
//'dom-ready',
'e2e-test-utils',
//'edit-post',
'element',
'escape-html',
//'html-entities',
//'i18n',
//'keycodes',
//'plugins',
//'priority-queue',
//'redux-routine',
//'rich-text',
//'shortcode',
//'url',
//'viewport',
//'wordcount',
];

let aggregatedExitCode = 0;
Expand All @@ -14,6 +40,7 @@ packages.forEach( ( packageName ) => {
`packages/${ packageName }/src/index.js`,
`--output packages/${ packageName }/README.md`,
'--to-token',
'--ignore "unstable|experimental"',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couple thoughts:

  • If this is a regular expression, should we be assuring ^ so that we'd not inadvertently ignore the token definitely_not_unstable (ignoring the fact this would, for other reasons, not be allowed)
  • The guidelines clearly prescribe the double-underscore __ prefix. I don't think we want the tolerance here. I want to see clear and loudly in the produced documentation if we're not naming these correctly.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I wanted a bit of leeway on purpose. There are a couple of offenders right now on master. Created #14337 to review this after all packages are set up.

];
const pathToDocGen = path.join( __dirname, '..', 'node_modules', '.bin', 'docgen' );
const { status, stderr } = childProcess.spawnSync(
Expand Down
114 changes: 114 additions & 0 deletions packages/escape-html/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,118 @@ npm install @wordpress/escape-html

_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._

## API

<!-- START TOKEN(Autogenerated API docs) -->

### escapeAmpersand

[src/index.js#L28-L30](src/index.js#L28-L30)

Returns a string with ampersands escaped. Note that this is an imperfect
implementation, where only ampersands which do not appear as a pattern of
named, decimal, or hexadecimal character references are escaped. Invalid
named references (i.e. ambiguous ampersand) are are still permitted.

**Related**

- <https://w3c.github.io/html/syntax.html#character-references>
- <https://w3c.github.io/html/syntax.html#ambiguous-ampersand>
- <https://w3c.github.io/html/syntax.html#named-character-references>

**Parameters**

- **value** `string`: Original string.

**Returns**

`string`: Escaped string.

### escapeAttribute

[src/index.js#L66-L68](src/index.js#L66-L68)

Returns an escaped attribute value.

**Related**

- <https://w3c.github.io/html/syntax.html#elements-attributes>

"[...] the text cannot contain an ambiguous ampersand [...] must not contain
any literal U+0022 QUOTATION MARK characters (")"

**Parameters**

- **value** `string`: Attribute value.

**Returns**

`string`: Escaped attribute value.

### escapeHTML

[src/index.js#L82-L84](src/index.js#L82-L84)

Returns an escaped HTML element value.

**Related**

- <https://w3c.github.io/html/syntax.html#writing-html-documents-elements>

"the text must not contain the character U+003C LESS-THAN SIGN (\<) or an
ambiguous ampersand."

**Parameters**

- **value** `string`: Element value.

**Returns**

`string`: Escaped HTML element value.

### escapeLessThan

[src/index.js#L50-L52](src/index.js#L50-L52)

Returns a string with less-than sign replaced.

**Parameters**

- **value** `string`: Original string.

**Returns**

`string`: Escaped string.

### escapeQuotationMark

[src/index.js#L39-L41](src/index.js#L39-L41)

Returns a string with quotation marks replaced.

**Parameters**

- **value** `string`: Original string.

**Returns**

`string`: Escaped string.

### isValidAttributeName

[src/index.js#L93-L95](src/index.js#L93-L95)

Returns true if the given attribute name is valid, or false otherwise.

**Parameters**

- **name** `string`: Attribute name to test.

**Returns**

`boolean`: Whether attribute is valid.


<!-- END TOKEN(Autogenerated API docs) -->

<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>