How to handle doc comments and examples?

[DerZade]

I want to use duplicate to create an asynchronous and a non-asynchronous version of a public method. Since this is a public API, I would like to have a proper doc comment and example. Currently both functions get the same comment, but I would like to have some small differences (especially in the example). Is there any way to achieve this?

[Emoun]

That's an interesting use case that I haven't thought of before and is a bit challenging.

First, the problem is that documentation comments are interpreted as strings, which duplicate does not look into for substitution. This means using /// comments will not work.
However, you can use documentation attributes directly and substitute the whole string:

#[duplicate_item(
  name             async     comment_sub;
  [some_fn]        [ ]       ["Comment for non-async"];
  [some_async_fn]  [async]   ["Comment for async"];
)]
/// Some comment that will not be substituted.
#[doc = comment_sub] 
async fn name() {
  ...
}

Notice how duplicate_item is before the comments. Putting it after will not work (it will not see them). This will result in:

/// Some comment that will not be substituted.
/// Comment for non-async
fn some_fn() {
  ...
}
/// Some comment that will not be substituted.
/// Comment for async
async fn some_async_fn() {
  ...
}

I hope this helps. Let me know how it works out.

[DerZade]

Interesting 🤔I'll try it out and let you know how and if it worked out 🙈

[DerZade]

After some testing, I can say that this works great for small differences, but is a bit unwieldy when trying to add different examples or something more complex.

I will probably use duplicate only for a private _impl function and then add several public functions manually with the proper doc comments wrapping only the _impl functions.

Thanks again for the very quick reply and the great crate. I'll close this as resolved 🙃

[Emoun]

but is a bit unwieldy when trying to add different examples or something more complex.

Yeah, I had a feeling that would be the case.
It's a nice workaround you found with _impl functions, but I'll think about whether substitutions within strings should be added to the crate. If you have feedback or examples you'd like me to take into account, feel free to drop it in #55.