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

Add internal documentation for all queries #104008

Open
jyn514 opened this issue Nov 5, 2022 · 1 comment
Open

Add internal documentation for all queries #104008

jyn514 opened this issue Nov 5, 2022 · 1 comment
Labels
A-contributor-roadblock Area: Makes things more difficult for new contributors to rust itself A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-query-system Area: The rustc query system (https://rustc-dev-guide.rust-lang.org/query.html) E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate.

Comments

@jyn514
Copy link
Member

jyn514 commented Nov 5, 2022

Currently, queries are inconsistently documented. Some have a doc-comment:

/// Return the span for a definition.
/// Contrary to `def_span` below, this query returns the full absolute span of the definition.
/// This span is meant for dep-tracking rather than diagnostics. It should not be used outside
/// of rustc_middle::hir::source_map.
query source_span(key: LocalDefId) -> Span {
desc { "getting the source span" }
}

while others only have the desc we mandate in the proc-macro:
query resolutions(_: ()) -> &'tcx ty::ResolverGlobalCtxt {
eval_always
no_hash
desc { "getting the resolver outputs" }
}

We should add documentation for all of these, then add #[warn(missing_docs)] so it doesn't regress in the future.

@jyn514 jyn514 added E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-query-system Area: The rustc query system (https://rustc-dev-guide.rust-lang.org/query.html) labels Nov 5, 2022
@Noratrieb
Copy link
Member

#[warn(missing_docs)] isn't quite enough, we'd also need to remove this default here:

let doc_string = format!("[query description - consider adding a doc-comment!] {}", doc_string);
Ok(parse_quote! { #[doc = #doc_string] })

@jyn514 jyn514 added the A-contributor-roadblock Area: Makes things more difficult for new contributors to rust itself label Nov 5, 2022
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Nov 6, 2022
…iler-errors

Add internal descriptions to a few queries

helps with rust-lang#104008
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Nov 6, 2022
…iler-errors

Add internal descriptions to a few queries

helps with rust-lang#104008
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-contributor-roadblock Area: Makes things more difficult for new contributors to rust itself A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-query-system Area: The rustc query system (https://rustc-dev-guide.rust-lang.org/query.html) E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate.
Projects
None yet
Development

No branches or pull requests

2 participants