Copy docs to getter in Properties macro

[carlosmn]

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.

[bilelmoussaoui]

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 Set $this_property or something like that?

[carlosmn]

By Set $property name do you mean if a line starts with that text, we'd consider the rest of the doc comments to be part of the setter? That is maybe a bit subtle but it does let you write a normal comment.

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.