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.

Sign up for GitHub

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

Improve autogenerated API docs #14549

Merged
merged 10 commits into from
Mar 27, 2019
Merged

Improve autogenerated API docs #14549

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
920036c
Improve the way symbols are documented
oandregal Mar 21, 2019
07ba5f1
lowercase anchor
oandregal Mar 21, 2019
dd1dac6
Use <> instead to path to source as link name
oandregal Mar 21, 2019
3beb2e6
Fix anchor name
oandregal Mar 21, 2019
e4ceb4d
Use same format for type and return tags
oandregal Mar 21, 2019
f1d2dda
Update test to new API
oandregal Mar 21, 2019
8c4e5bf
Update test to new output
oandregal Mar 21, 2019
ef5ce25
Bring back param names
oandregal Mar 21, 2019
c741079
Update e2e-test-utils
oandregal Mar 22, 2019
c4cadf2
Format recently added data package
oandregal Mar 27, 2019
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
16 changes: 6 additions & 10 deletions packages/a11y/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,20 +16,16 @@ _This package assumes that your code will run in an **ES2015+** environment. If

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

### setup

[src/index.js#L16-L26](src/index.js#L16-L26)
<a name="setup" href="#setup">#</a> **setup** [\<>](src/index.js#L16-L26)
Copy link
Member

Choose a reason for hiding this comment

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

Maybe not to be addressed here, but the relative links for code are dead links in NPM:

https://www.npmjs.com/package/@wordpress/a11y

It appears NPM tries to append it to the GitHub repository, and it may be that once they properly support the new repository.directory on their website it becomes fixed.

Copy link
Member

Choose a reason for hiding this comment

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

Curious, was there some prior art for the <> ? Is it meant to be an abbreviated message of "this is the code!" ? Once I understood it, it seemed fine enough. But I'd be lying if I said my initial reaction wasn't to consider it as being some erroneous output.

Copy link
Member Author

@oandregal oandregal Mar 21, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

Yeah, there is an issue for the links. I plan to address it next. It's also a problem in the handbook.

The <> idea I took it from D3 API docs such as: https://github.com/d3/d3-brush/blob/master/README.md#api-reference

Copy link
Member

Choose a reason for hiding this comment

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

I'd be curious if NPM would strip anything of the custom anchor tag. Is there a reason it ought not be a heading, or is that the idea of "toning down"? Structurally / semantically, it seemed to make sense as a heading.

Copy link
Member Author

Choose a reason for hiding this comment

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

Not really, just that this approach made the symbols more prominent. I'm on mobile now but can upload some before/after images.

Copy link
Member

Choose a reason for hiding this comment

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

Since it's auto-generated it probably doesn't matter that much whether we use heading. However, I'm curious if we could keep h3 as it helped to give more focus to the method name.

Copy link
Member

Choose a reason for hiding this comment

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

Were you still planning to apply the code formatting, as per #14290 ?

Copy link
Member Author

Choose a reason for hiding this comment

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

Tried that as well but liked this more.


Create the live regions.

### speak

[src/index.js#L52-L66](src/index.js#L52-L66)
<a name="speak" href="#speak">#</a> **speak** [\<>](src/index.js#L52-L66)

Allows you to easily announce dynamic interface updates to screen readers using ARIA live regions.
This module is inspired by the `speak` function in wp-a11y.js

**Usage**
_Usage_

```js
import { speak } from '@wordpress/a11y';
Expand All @@ -41,10 +37,10 @@ speak( 'The message you want to send to the ARIA live region' );
speak( 'The message you want to send to the ARIA live region', 'assertive' );
```

**Parameters**
_Parameters_

- **message** `string`: The message to be announced by Assistive Technologies.
- **ariaLive** `string`: Optional. The politeness level for aria-live. Possible values: polite or assertive. Default polite.
- _message_ `string`: The message to be announced by Assistive Technologies.
- _ariaLive_ `string`: Optional. The politeness level for aria-live. Possible values: polite or assertive. Default polite.


<!-- END TOKEN(Autogenerated API docs) -->
Expand Down
30 changes: 13 additions & 17 deletions packages/autop/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,55 +16,51 @@ _This package assumes that your code will run in an **ES2015+** environment. If

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

#### autop

[src/index.js#L129-L285](src/index.js#L129-L285)
<a name="autop" href="#autop">#</a> **autop** [\<>](src/index.js#L129-L285)

Replaces double line-breaks with paragraph elements.

A group of regex replaces used to identify text formatted with newlines and
replace double line-breaks with HTML paragraph tags. The remaining line-
breaks after conversion become `<br />` tags, unless br is set to 'false'.

**Usage**
_Usage_

```js
import { autop } from '@wordpress/autop';
autop( 'my text' ); // "<p>my text</p>"
```

**Parameters**

- **text** `string`: The text which has to be formatted.
- **br** `boolean`: Optional. If set, will convert all remaining line- breaks after paragraphing. Default true.
_Parameters_

**Returns**
- _text_ `string`: The text which has to be formatted.
- _br_ `boolean`: Optional. If set, will convert all remaining line- breaks after paragraphing. Default true.

`string`: Text which has been converted into paragraph tags.
_Returns_

#### removep
- `string`: Text which has been converted into paragraph tags.

[src/index.js#L303-L426](src/index.js#L303-L426)
<a name="removep" href="#removep">#</a> **removep** [\<>](src/index.js#L303-L426)

Replaces `<p>` tags with two line breaks. "Opposite" of autop().

Replaces `<p>` tags with two line breaks except where the `<p>` has attributes.
Unifies whitespace. Indents `<li>`, `<dt>` and `<dd>` for better readability.

**Usage**
_Usage_

```js
import { removep } from '@wordpress/autop';
removep( '<p>my text</p>' ); // "my text"
```

**Parameters**
_Parameters_

- **html** `string`: The content from the editor.
- _html_ `string`: The content from the editor.

**Returns**
_Returns_

`string`: The content with stripped paragraph tags.
- `string`: The content with stripped paragraph tags.


<!-- END TOKEN(Autogenerated API docs) -->
Expand Down
44 changes: 18 additions & 26 deletions packages/blob/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,59 +14,51 @@ npm install @wordpress/blob --save

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

### createBlobURL

[src/index.js#L15-L21](src/index.js#L15-L21)
<a name="createBlobURL" href="#createBlobURL">#</a> **createBlobURL** [\<>](src/index.js#L15-L21)

Create a blob URL from a file.

**Parameters**

- **file** `File`: The file to create a blob URL for.
_Parameters_

**Returns**
- _file_ `File`: The file to create a blob URL for.

`string`: The blob URL.
_Returns_

### getBlobByURL
- `string`: The blob URL.

[src/index.js#L32-L34](src/index.js#L32-L34)
<a name="getBlobByURL" href="#getBlobByURL">#</a> **getBlobByURL** [\<>](src/index.js#L32-L34)

Retrieve a file based on a blob URL. The file must have been created by
`createBlobURL` and not removed by `revokeBlobURL`, otherwise it will return
`undefined`.

**Parameters**
_Parameters_

- **url** `string`: The blob URL.
- _url_ `string`: The blob URL.

**Returns**
_Returns_

`?File`: The file for the blob URL.
- `?File`: The file for the blob URL.

### isBlobURL

[src/index.js#L56-L61](src/index.js#L56-L61)
<a name="isBlobURL" href="#isBlobURL">#</a> **isBlobURL** [\<>](src/index.js#L56-L61)

Check whether a url is a blob url.

**Parameters**

- **url** `string`: The URL.
_Parameters_

**Returns**
- _url_ `string`: The URL.

`boolean`: Is the url a blob url?
_Returns_

### revokeBlobURL
- `boolean`: Is the url a blob url?

[src/index.js#L41-L47](src/index.js#L41-L47)
<a name="revokeBlobURL" href="#revokeBlobURL">#</a> **revokeBlobURL** [\<>](src/index.js#L41-L47)

Remove the resource and file cache from memory.

**Parameters**
_Parameters_

- **url** `string`: The blob URL.
- _url_ `string`: The blob URL.


<!-- END TOKEN(Autogenerated API docs) -->
Expand Down
Loading