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

doc: prepare miscellaneous docs for new markdown lint rules #29963

Merged
merged 0 commits into from Oct 15, 2019

Conversation

@Trott
Copy link
Member

Trott commented Oct 14, 2019

Prepare the final few documents that haven't been updated to always use
[] with reference links and to escape [ and ] for things that
aren't links in markdown files.

These are the final changes required before we can use the next version of remark-preset-lint-node.

@nschonni @nodejs/documentation

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines
@Trott

This comment has been minimized.

Copy link
Member Author

Trott commented Oct 14, 2019

Collaborators, please 👍 here to fast-track.

@Trott

This comment has been minimized.

Copy link
Member Author

Trott commented Oct 14, 2019

@Trott Trott added the fast-track label Oct 14, 2019
* `buf` [<Buffer>]
* return [<ArrayBufferView[]>]
* `buf` [<Buffer>][]
* return [<ArrayBufferView>][]\[\]

This comment has been minimized.

Copy link
@nschonni

nschonni Oct 14, 2019

Member

Think the reference link might need to be updated instead for the 3 in this section to include the array modifier in the identifier

This comment has been minimized.

Copy link
@nschonni

nschonni Oct 14, 2019

Member

The current way does work though

This comment has been minimized.

Copy link
@Trott

Trott Oct 14, 2019

Author Member

My thinking in preferring this way is that the linked info is not about ArrayBufferView[]. It's about ArrayBufferView. So the link text reflects that.

@Trott Trott added the author ready label Oct 14, 2019
@XhmikosR

This comment has been minimized.

Copy link
Member

XhmikosR commented Oct 14, 2019

Escaping the square brackets is not needed AFAICT. Which tool complains?

EDIT: For example, this shows just fine without escaping [ https://github.com/nodejs/node/tree/master/benchmark#createbenchmarkfn-configs-options

@Trott

This comment has been minimized.

Copy link
Member Author

Trott commented Oct 14, 2019

Escaping the square brackets is not needed AFAICT. Which tool complains?

EDIT: For example, this shows just fine without escaping [ https://github.com/nodejs/node/tree/master/benchmark#createbenchmarkfn-configs-options

It makes the text a link (without displaying brackets at all) if the text happens to match a bottom-reference, which it did in one case that @nschonni found. So it only causes problems infrequently. Or at least that's my understanding. Maybe @nschonni can confirm/clarify.

@nschonni

This comment has been minimized.

Copy link
Member

nschonni commented Oct 14, 2019

@Trott

This comment has been minimized.

Copy link
Member Author

Trott commented Oct 14, 2019

The instance this did flag correctly was #29809 (comment) and the rule that flags it is https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-undefined-references

And in the current version of the docs (for 12.12.0), you can see the problem: https://nodejs.org/dist/latest-v12.x/docs/api/crypto.html#crypto_diffiehellman_generatekeys_encoding

The brackets are gone and "encoding" is now link text.

@nschonni

This comment has been minimized.

Copy link
Member

nschonni commented Oct 15, 2019

From the upstream build failure, there are a few new ones in doc/api/vm.md

tmp/doc/api/vm.md
  315:28-315:45  warning  Found reference to undefined definition               no-undefined-references     remark-lint
  565:46-565:57  warning  Use the trailing [] on reference links                no-shortcut-reference-link  remark-lint
  565:46-565:57  warning  Found reference to undefined definition               no-undefined-references     remark-lint
  656:70-656:81  warning  Use the trailing [] on reference links                no-shortcut-reference-link  remark-lint
  656:70-656:81  warning  Found reference to undefined definition               no-undefined-references     remark-lint
@Trott

This comment has been minimized.

Copy link
Member Author

Trott commented Oct 15, 2019

From the upstream build failure, there are a few new ones in doc/api/vm.md

tmp/doc/api/vm.md
  315:28-315:45  warning  Found reference to undefined definition               no-undefined-references     remark-lint
  565:46-565:57  warning  Use the trailing [] on reference links                no-shortcut-reference-link  remark-lint
  565:46-565:57  warning  Found reference to undefined definition               no-undefined-references     remark-lint
  656:70-656:81  warning  Use the trailing [] on reference links                no-shortcut-reference-link  remark-lint
  656:70-656:81  warning  Found reference to undefined definition               no-undefined-references     remark-lint

Good to know. I'm OK with fixing those up when the lint rule lands on master, just as long as there's three lines to fix and not 150.

@XhmikosR

This comment has been minimized.

Copy link
Member

XhmikosR commented Oct 15, 2019

It's no big deal, I'm just trying to understand why perfectly fine square brackets are flagged. Are the docs being built here on CI? Is the output the same?

@Trott

This comment has been minimized.

Copy link
Member Author

Trott commented Oct 15, 2019

It's no big deal, I'm just trying to understand why perfectly fine square brackets are flagged. Are the docs being built here on CI? Is the output the same?

Docs are built on CI so that if any changes to the docs happen that break doctool or whatever, we know. I don't think that output is checked, but I don't have any reason to believe it's different than when people run locally.

@Trott

This comment has been minimized.

Copy link
Member Author

Trott commented Oct 15, 2019

Landed in ed5eaa0

@Trott Trott closed this Oct 15, 2019
@Trott Trott force-pushed the Trott:update-md-linting branch from da5538f to ed5eaa0 Oct 15, 2019
@Trott Trott merged commit ed5eaa0 into nodejs:master Oct 15, 2019
targos added a commit that referenced this pull request Nov 8, 2019
Prepare the final few documents that haven't been updated to always use
`[]` with reference links and to escape `[` and `]` for things that
aren't links in markdown files.

PR-URL: #29963
Reviewed-By: Masashi Hirano <shisama07@gmail.com>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
targos added a commit that referenced this pull request Nov 10, 2019
Prepare the final few documents that haven't been updated to always use
`[]` with reference links and to escape `[` and `]` for things that
aren't links in markdown files.

PR-URL: #29963
Reviewed-By: Masashi Hirano <shisama07@gmail.com>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
8 participants
You can’t perform that action at this time.