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

Jump to bottom

Auto-generate lint documentation #349

Closed
1 of 3 tasks
ehuss opened this issue Aug 22, 2020 · 2 comments
Closed
1 of 3 tasks

Auto-generate lint documentation #349

ehuss opened this issue Aug 22, 2020 · 2 comments
Labels
major-change A proposal to make a major change to rustc major-change-accepted A major change proposal that was accepted T-compiler Add this label so rfcbot knows to poll the compiler team

Comments

@ehuss
Copy link

ehuss commented Aug 22, 2020

Proposal

I would like to implement a change so that the lint documentation is automatically generated from the lint definitions.

The lint listing at https://doc.rust-lang.org/rustc/lints/listing/index.html is out of date. It requires manual maintenance, which few people bother with.

The change would be to move the documentation into the declare_lint macro. This is how clippy does it (example), and I would suggest using a similar form. Then, a simple script would be used when building the rustc book to extract the documentation and place it in the book (similar to how clippy does which is displayed on github pages here), though I would probably just retain the current formatting. Additionally, I would like to add a test to ensure the examples work as expected (generate the expected lint).

A future extension (not proposed for now), is to provide more convenient access to this documentation, similar to how errors point to the error index with the --explain flag.

Mentors or Reviewers

Process

The main points of the Major Change Process is as follows:

  • File an issue describing the proposal.
  • A compiler team member or contributor who is knowledgeable in the area can second by writing @rustbot second.
    • Finding a "second" suffices for internal changes. If however you are proposing a new public-facing feature, such as a -C flag, then full team check-off is required.
    • Compiler team members can initiate a check-off via @rfcbot fcp merge on either the MCP or the PR.
  • Once an MCP is seconded, the Final Comment Period begins. If no objections are raised after 10 days, the MCP is considered approved.

You can read more about Major Change Proposals on forge.

Comments

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.
@ehuss ehuss added T-compiler Add this label so rfcbot knows to poll the compiler team major-change A proposal to make a major change to rustc labels Aug 22, 2020
@rustbot
Copy link
Collaborator

rustbot commented Aug 22, 2020

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

@rustbot rustbot added the to-announce Announce this issue on triage meeting label Aug 22, 2020
@wesleywiser
Copy link
Member

@rustbot second

I would also be happy to do the reviews for this.

@rustbot rustbot added the final-comment-period The FCP has started, most (if not all) team members are in agreement label Aug 23, 2020
@spastorino spastorino added major-change-accepted A major change proposal that was accepted and removed to-announce Announce this issue on triage meeting final-comment-period The FCP has started, most (if not all) team members are in agreement labels Aug 26, 2020
@rustbot rustbot added the to-announce Announce this issue on triage meeting label Sep 2, 2020
@spastorino spastorino removed the to-announce Announce this issue on triage meeting label Sep 2, 2020
@ehuss ehuss mentioned this issue Sep 10, 2020
Merged
bors added a commit to rust-lang-ci/rust that referenced this issue Sep 14, 2020
@bors
Auto merge of rust-lang#76549 - ehuss:lints-comments, r=wesleywiser
b5f55b7 
Auto-generate lint documentation.

This adds a tool which will generate the lint documentation in the rustc book automatically. This is motivated by keeping the documentation up-to-date, and consistently formatted. It also ensures the examples are correct and that they actually generate the expected lint. The lint groups table is also auto-generated. See rust-lang/compiler-team#349 for the original proposal.

An outline of how this works:
- The `declare_lint!` macro now accepts a doc comment where the documentation is written. This is inspired by how clippy works.
- A new tool `src/tools/lint-docs` scrapes the documentation and adds it to the rustc book during the build.
    - It runs each example and verifies its output and embeds the output in the book.
    - It does a few formatting checks.
    - It verifies that every lint is documented.
- Groups are collected from `rustc -W help`.

I updated the documentation for all the missing lints. I have also added an "Explanation" section to each lint providing a reason for the lint and suggestions on how to resolve it.

This can lead towards a future enhancement of possibly showing these docs via the `--explain` flag to make them easily accessible and discoverable.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
major-change A proposal to make a major change to rustc major-change-accepted A major change proposal that was accepted T-compiler Add this label so rfcbot knows to poll the compiler team
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@ehuss @spastorino @wesleywiser @rustbot