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

rustdoc: Add ItemTemplate trait and related functions to avoid repetitively wrapping existing functions #111946

Merged
merged 1 commit into from
May 27, 2023
Merged

rustdoc: Add ItemTemplate trait and related functions to avoid repetitively wrapping existing functions #111946

merged 1 commit into from
May 27, 2023

Conversation

nicklimmm
Copy link
Contributor

Context: #111430 (comment)

This trait will be used extensively in performing migrations to Askama templates (tracking issue: #108868)

@rustbot
Copy link
Collaborator

rustbot commented May 25, 2023

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @jsha (or someone else) soon.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

  • @rustbot author: the review is finished, PR author should check the comments and take action accordingly
  • @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels May 25, 2023
@nicklimmm
Copy link
Contributor Author

r? @GuillaumeGomez

@rustbot rustbot assigned GuillaumeGomez and unassigned jsha May 25, 2023
@nicklimmm
Copy link
Contributor Author

nicklimmm commented May 25, 2023 •
edited
Loading

FYI: "Return position impl Trait in traits" RFC is now entering its final comment period (comment)

Through this, we might be able to enhance the trait further.

GuillaumeGomez
GuillaumeGomez reviewed May 26, 2023
View reviewed changes
src/librustdoc/html/templates/item_union.html
@@ -19,5 +19,5 @@ <h2 id="fields" class="fields small-section-header">
{{ self.document_field(field) | safe }}
{% endfor %}
{% endif %}
{{ self.render_assoc_items() | safe }}
{{ self.document_type_layout() | safe }}
{{ self::item_template_render_assoc_items(self.borrow()) | safe }}
Copy link
Member

Choose a reason for hiding this comment

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

I just thought about something: could we instead of calling .borrow() change the API of item_template_render_assoc_items to take a &RefCell<T> where T: ItemTemplate or something equivalent to not have to write .borrow() every time? I'm not sure if it's possible though. If you could confirm it, it'd be awesome!

Copy link
Contributor Author

@nicklimmm nicklimmm May 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

self::item_template_render_attributes_in_pre(self) | safe expands to

  • Without .borrow(): &::askama::filters::safe(::askama::Html, self::item_template_render_attributes_in_pre(&(self)))?
  • With .borrow(): &::askama::filters::safe(::askama::Html, self::item_template_render_attributes_in_pre({self.borrow()}))?

I'm not sure why the function didn't catch &(self) as &impl ItemTemplate, but self.borrow() does here (self.borrow() returns &ItemUnion) ...

Copy link
Contributor Author

@nicklimmm nicklimmm May 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

I found out that we can remove .borrow() calls by:

  • Implementing ItemTemplate trait for &ItemUnion
    • The compiler suggested this after I removed .borrow()
    • We should use blanket impls to prevent writing the same impl blocks multiple times
  • Implementing askama::Template trait for &ItemUnion
    • Due to the derive macro doesn't implement askama::Template for &T
    • Can't apply blanket impls here since Template is from an external crate (not sure if we should make a feature request for this to be available)
    • Implication: we need to copy over the associated types and wrap methods from T
    • Possible to use macros here

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'm pretty much stuck at this point, what do you think? @GuillaumeGomez

Copy link
Member

Choose a reason for hiding this comment

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

I really like the first suggestion which also seems to be the simplest to be implemented (but maybe I'm wrong there). Thanks for taking a look! So what do you prefer: making the changes here directly or opening an issue and fixing it in a follow-up PR?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Oops, I laid them out wrongly, they should be implemented together.

Doing only the 1st item will cause errors, and the compiler suggested to do the 2nd item to fix it.

Copy link
Member

Choose a reason for hiding this comment

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

Oh I see. Well, that still seems doable. Then same question for how you prefer things to roll out. :)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I really like the first suggestion which also seems to be the simplest to be implemented (but maybe I'm wrong there). Thanks for taking a look! So what do you prefer: making the changes here directly or opening an issue and fixing it in a follow-up PR?

Nevertheless, I'd prefer to do a follow-up PR and open up a new issue. I would like to see opinions from others (in case there exists something simpler).

Copy link
Member

Choose a reason for hiding this comment

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

Let's go this way then! I r+ this PR. Please open an issue. ;)

@GuillaumeGomez
Copy link
Member

Looks good to me, thanks! Just one thing I'm wondering about but after that we can merge.

@GuillaumeGomez
Copy link
Member

Thanks for the work!

@bors r+ rollup

@bors
Copy link
Contributor

bors commented May 27, 2023

📌 Commit fbdc511 has been approved by GuillaumeGomez

It is now in the queue for this repository.

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 27, 2023
@nicklimmm nicklimmm mentioned this pull request May 27, 2023
Closed
2 tasks
@matthiaskrgr matthiaskrgr mentioned this pull request May 27, 2023
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request May 27, 2023
@bors
Auto merge of rust-lang#112025 - matthiaskrgr:rollup-j693v67, r=matth…
cca7ee5 
…iaskrgr

Rollup of 6 pull requests

Successful merges:

 - rust-lang#108630 (Fix docs for `alloc::realloc`)
 - rust-lang#109084 (rustc driver: Remove argument 0 before at-expansion to prevent ICE)
 - rust-lang#111181 (fix(parse): return unpected when current token is EOF)
 - rust-lang#111656 (Use an unbounded lifetime in `String::leak`.)
 - rust-lang#111946 (rustdoc: Add `ItemTemplate` trait and related functions to avoid repetitively wrapping existing functions)
 - rust-lang#112018 (Clean up usage of `cx.tcx` when `tcx` is already set into a variable)

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 9a4fce9 into rust-lang:master May 27, 2023
@rustbot rustbot added this to the 1.71.0 milestone May 27, 2023
@nicklimmm nicklimmm mentioned this pull request Jun 2, 2023
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Jun 11, 2023
@bors
Auto merge of rust-lang#112202 - nicklimmm:item-template-derive-macro…
7b6093e 
…, r=GuillaumeGomez

rustdoc: Add `item_template` macro

Closes rust-lang#112021

This change removes the use of `self.borrows()` in Askama templates, removes code duplication from `item_and_mut_cx()`, and improved readability by eliminating the prefix `item_template_` when calling from the template.

References:
- Discussion issue: rust-lang#112021
- `ItemTemplate` PR: rust-lang#111946

r? `@GuillaumeGomez`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@GuillaumeGomez GuillaumeGomez GuillaumeGomez left review comments

Assignees

@GuillaumeGomez GuillaumeGomez

Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.71.0
Development

Successfully merging this pull request may close these issues.
5 participants
@nicklimmm @rustbot @GuillaumeGomez @bors @jsha