Object Reform obscures documentation for wrapped types
jashephe opened this issue · comments
Although @gkoz's object reform PR improved the handling of wrapped types, it resulted in the generated rustdoc pages not showing the documentation for associated methods (look at the documentation page for Pixbuf for an example). This is probably a rustdoc problem, but is there anything we can do to make the docs visible?
Bummer.
We'll probably have to resort to some code duplication, remove the generic Object<T> struct and make each type its own newtype. Possibly using a macro like rgtk did.
Another problem is that even with that out of the way rustdoc won't show that e.g. PixbufAnimation and PixbufSimpleAnim implement PixbufAnimationExt and I'm not sure how to fix this. Just reference the applicable traits in the doc comments?
This is not a big deal in gdk but will be a problem in gtk, so thanks for bringing this up before I made all of gtk like this :)
@jashephe
I see you've already identified one or more relevant open issues in the rust repo. Could you link them here?
@gkoz, I'm not sure what you mean. I haven't seen a relevant rustdoc issue, I just assumed that rustdoc was to blame.
I thought I saw your comment in one of rustdoc issues...
Ah, that was actually for a different, but perhaps related issue. The implementation of ContextExt for Context is not shown in the documentation for rust-gnome/gdk, because Context is not part of the gdk crate. I was able to get around it by documenting the ContextExt trait method definitions, rather than the implementing methods.
Here's that issue, but it's not quite the same as what's going on here.
The type aliases issue: rust-lang/rust#19381
The blanket impls issue: rust-lang/rust#25608
I'm hopeful this can be fixed in rustdoc rather than by hoop-jumping.
It doesn't look like either of those issues has received much attention, unfortunately.
@gkoz, did your pull request (rust-lang/rust#25892) fix this issue? Why exactly was it closed?
That was a hack that didn't get much support because of the limitations of a 10-line patch.
It wouldn't buy us much anyway and could be worked around. The big stopper is rust-lang/rust#25608 (possibly with added transitivity requirement) because most of the invisible documentation would be of the impl <O: Upcast<Window>> WindowExt for O kind.
Inherent implementations should be visible now. The blanket implementations issue probably requires rewriting rustdoc.