Copy docs to getter in Properties macro #1490
Conversation
sdroege
added
the
needs-backport
|
I am fine with the changes but we need to first come up with at least an approach on how to handle the setters/notify functions docs. Could we just auto-generate them based on |
|
By I wonder if a pseudo-attribute would work, something like /// Here I am writing my comment for the getter
///
/// #[setter]
///
/// And now I'm writing docs for the setter.
Then again this works the other way around to how you write doc comments so maybe it's the other way around that matches how you would expect it to be in actual Rust. Or there's also adding more actual attributes for us to read, though I haven't checked how awkward it would be to parse this, something like /// Comments for the getter
#[getter]
/// And for the setter
#[setter]
#[property(get, set)]though it makes it more awkward to write. I don't know how possible it is (and it would be really ugly, I think) but you could also put the comments where you define that you have a getter and setter #[property(
/// Some comment for the getter
get,
/// And a comment for the setter
set]but maybe that's just too ugly and awkward a syntax to ask people to write. |
|
Tbh, I don't have any ideas here that is why I didn't reply earlier. I just don't want people to refactor a bunch of code in case the to be added setter support makes the getter docs behave differently. |
|
Yeah, there's no obviously good answer unfortunately. A variant I just though of is using Of course that's only a little bit like this as clippy isn't doing anything beyond seeing that the line exists, and it doesn't affect how the docs generate anything. So it's not the strongest precedent, but having /// Comments for the getter
///
/// # Setter
///
/// And for the setter
#[property(get, set)]seems like it flows when writing it and it's something you can parse and relate to other cases (though maybe not all that many people are actually writing unsafe functions). |
|
I would say using # Getter and # Setter would be good. As we also have # Notify for the generted notify_$property. And leave any comment before that relevant to the field as it might be some in code explanation |
|
Ok that seems reasonable, so we'd end up like /// Some comments that remain internal
///
/// # Getter
///
/// Docs that land in the getter
///
/// # Setter
///
/// And docs for the setter
#[property(get, set)] |
|
I'm now thinking that we have two kinds of docs here: in one situation you're fine with the same doc on both setter and getter, and then sometimes it's important to specify something about the getter or setter. So alongside the headings, I think it makes sense to allow for the simple case of just copying the doc to both setter and getter if you don't opt into defining them. |
These will be used later on by the macro.
We take the docs directly preceding a `#[property]` and copy them into the generated getter method.
In the previous commit we made it so we copy the docs for a `#[property]` in to the getter. This was an improvement but it still did not allow for any doc comments on the setter that might be relevant only there. Here we introduce the ability to specify doc comments for the getter and setter individually via the use of the header syntax to switch between them. By writing `# Getter` or `# Setter` in a line, you make the lines following it go to the getter or setter function definitions. If neither of these values exist, we copy the doc comments to both. If you use these values, then anything in the doc comments before the first one is discarded.
Let's copy the comments as part of the `parse_quote_spanned!` when we create the rest of the tokens for the code instead of adding it after the fact.
carlosmn
force-pushed
the
cmn/properties-macro-docs
branch
from
b3b6241 to
bf86950
Compare
|
Ok well I finally found time/motivation to look back into this and just ended up taking a few hours. This now implements what we discussed as a reasonable compromise which includes an example so you can check it while messing around with the code. If this does seem like we want then these comment copy rules and example should end up in |
Spurred by #1236 though there's probably more we can do here.
The change here is that we take anything that's a doc before a
#[property]and consider that to be the docs for the getter, as it seems like the getter and the property would be the most likely to share doc comments.There is of course an open question of what one could do to get docs for the setter that aren't a pain to write, but at least for the setter we can make something that, I think, makes intuitive sense.
The big issue here is that you wouldn't get docs copied over if you add a doc to the field but after the
#[property]. This is probably something we could allow, but I don't know how important it would be.