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

docs: add docs for check options #2406

Merged
merged 28 commits into from
Jul 29, 2020
Merged

docs: add docs for check options #2406

merged 28 commits into from
Jul 29, 2020

Conversation

straker
Copy link
Contributor

@straker straker commented Jul 21, 2020

I only included checks whose options modified how the check behaved. Checks which used generic checks (such as non-empty-title) were not added to list as their options are not really there for the user to customize. Generic checks will be described in another doc about creating custom rules.

Note: I do not understand what all the options for p-as-heading do even from looking at the code. If anyone can provide that understanding that'd be great.

Rendered view https://github.com/dequelabs/axe-core/blob/62e559fd7c65b8f426d01d99803854b3b9dcef6c/doc/check-options.md

Closes issue: #2187

Reviewer checks

Required fields, to be filled out by PR reviewer(s)

  • Follows the commit message policy, appropriate for next version
  • Code is reviewed for security

@straker straker requested a review from a team as a code owner July 21, 2020 17:53
Copy link
Contributor

@jeankaplansky jeankaplansky left a comment

Choose a reason for hiding this comment

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

RE: @straker's message above about not understanding all the options for p-as-heading - does https://dequeuniversity.com/rules/axe/3.5/p-as-heading clear it up for you?

Including a link to https://dequeuniversity.com/rules/axe rule help may be a valuable reference to other people. It can help people understand what a rule is supposed to do in addition to understanding why we check for one or more options.

}
]
});
```
Copy link
Contributor

Choose a reason for hiding this comment

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

something's wonky with the rendered codelisting formatting here:

image

Copy link
Member

Choose a reason for hiding this comment

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

Aside from it being hard to read (due to the tabs), I don't see anything "wonky" here.

Copy link
Contributor

Choose a reason for hiding this comment

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

It looks like a linter gone wild thing. The code itself looks fine. Github rendering, not so much.

Copy link
Member

Choose a reason for hiding this comment

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

I'm not sure what you're suggesting here. Is there anything that should be "fixed"?

Copy link
Contributor

Choose a reason for hiding this comment

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

@stephenmathieson: not if the 2 spaces = indentation/prettier stuff is working, no. It's up to Github to render it properly.

Copy link
Member

Choose a reason for hiding this comment

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

I do not understand.

Copy link
Member

@stephenmathieson stephenmathieson left a comment

Choose a reason for hiding this comment

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

While I think it's a good idea to document all of this, I fear that it's going to get out-of-date very quickly (and/or be a pain to maintain). Is there a way we could generate this document instead? Perhaps we could parse the JSDoc strings from the check code and build a .md file from them?

Copy link
Contributor

@jeankaplansky jeankaplansky left a comment

Choose a reason for hiding this comment

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

I think there's something to be gained by indicating what "kind of beast" the default values are - if they are CSS selectors, CSS properties on a selector, attribute values, ARIA-specific attr values. Anything that helps the end-user figure out what they're looking at and where it fits in the HTML context.

doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
doc/check-options.md Outdated Show resolved Hide resolved
straker and others added 12 commits July 22, 2020 15:06
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
straker and others added 10 commits July 24, 2020 09:18
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
Co-authored-by: Jean Kaplansky <jeankaplansky@users.noreply.github.com>
@straker
Copy link
Contributor Author

straker commented Jul 24, 2020

Table formatting is so much fun

@straker straker merged commit a804253 into develop Jul 29, 2020
@straker straker deleted the check-options-doc branch July 29, 2020 15:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants