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

Handle comments that look like HTML tags but aren't #381

Open
Tracked by #486
coryan opened this issue Dec 9, 2024 · 2 comments · May be fixed by #801
Open
Tracked by #486

Handle comments that look like HTML tags but aren't #381

coryan opened this issue Dec 9, 2024 · 2 comments · May be fixed by #801
Assignees
@mpeddada1
Labels
priority: p3 Desirable enhancement or fix. May not be included in next release. sidekick Issues related to the code generator type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design.

Comments

@coryan
Copy link
Contributor

coryan commented Dec 9, 2024 •
edited
Loading

Consider this:

google-cloud-rust/src/gax/src/error/rpc/generated/mod.rs

Lines 199 to 200 in 2c05b48

/// For example, "clientip:<ip address of client>" or "project:<Google
/// developer project id>".

Rustdoc treats <ip ...> and <Google ...> as HTML tags. This creates two problems:

  1. rustdoc warngs complains that they are not closed, and 
    warning: unclosed HTML tag `ip`
--> src/gax/src/error/rpc/generated/mod.rs:198:9
    |
198 | /         /// The subject on which the quota check failed.
199 | |         /// For example, "clientip:<ip address of client>" or "project:<Google
200 | |         /// developer project id>".
    | |___________________________________^
  2. rustdoc removes them from the output:
    image

Either we change all the cases of placeholders using <... >, or we escape these placeholders in the Rust code to keep these in the documentation output.

To my knowledge, the only relevant API ( aip/192 says nothing about such "almost looks like a tag" problems.
@coryan coryan added type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design. priority: p3 Desirable enhancement or fix. May not be included in next release. labels Dec 9, 2024
@coryan
Copy link
Contributor Author

coryan commented Dec 9, 2024

Maybe all we need to do is disable this warning for generated code:

https://doc.rust-lang.org/rustdoc/lints.html#invalid_html_tags

@coryan
Copy link
Contributor Author

coryan commented Dec 13, 2024

FWIW, in #409 I disabled the warnings about these things. The generated documentation skips the thing that looks like a tag, so the problems from the description remains.

@coryan coryan added the sidekick Issues related to the code generator label Dec 13, 2024
@coryan coryan mentioned this issue Dec 19, 2024
Open
3 tasks
@mpeddada1 mpeddada1 self-assigned this Jan 21, 2025
This was referenced Jan 22, 2025
Draft
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@mpeddada1 mpeddada1

Labels
priority: p3 Desirable enhancement or fix. May not be included in next release. sidekick Issues related to the code generator type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

fix: escape html tags for placeholders in comments mpeddada1/google-cloud-rust
2 participants
@coryan @mpeddada1