Bus::get_pollfd generate doc for both unix & windows

[fengalin]

There are different implementations and signatures for get_pollfd depending
on whether the target platform is unix or windows. When generating the doc,
we need both implementations to appear regardless of the target platform. This
commit is inspired by the way Rust std library deals with process::Command
OS dependent variants.

Documentation can't be accurate though as we can't use thestd::os::windows
on unix and vice versa. As a workaround a fake fd class matching the other
platform is declared.

This could be further enhanced once #[doc(cfg(...))] is stabilized
by declaring #[doc(cfg(unix))] or #[doc(cfg(windows))] instead of the hard coded
comments This is supported on **Windows/Unix** only. Unfortunately, these
comments disappear when generating with --all-features because they are not part
of the documentation in the gir file. Is there a way to prevent them from being removed?

[fengalin]

Please note the comment from commit 5fe5318:

Inclusion of this commit is debatable because the "other" platform's doc
for BustExtManual shows a trait named WindowsBusExtManual which could
be missleading. Maybe is it better not to advertize the trait in the
prelude documentation than advertizing something under an incorrect name.
OTOH, it is in the prelude so that de user doesn't have to worry about it.

Note that this behaviour is also present when searching for traits. So,
the only place where it appears correctly is in the Bus page, but the
comments about them being platform specific is removed when generating with
gir comments...

[sdroege]

Sounds like all options are bad :) I'll think about it a bit, thanks!

[fengalin]

There might be yet another way, defining an OS independent alias for unix::io::RawFd and windows::io::RawHandle so that the return type for get_pollfd is always e.g. PollFd, just like in the C implementation. This way, there wouldn't be any duplicate signature nor confusing trait. The only remaining oddity would be the type not being navigable to the actual std type for the "other" platform in the documentation (not sure I'm quite clear here :)).

Too bad the message "This is supported on Windows/Unix only" is removed when generating doc with gir, otherwise I believe the resulting documentation for Bus would be worth the misleading trait (see the result when running cargo doc --features dox). I think you need the first commit anyway.

[sdroege]

Maybe we can always call the traits BusExtManualUnix and BusExtManualWindows? That would seem less confusing.

Otherwise this looks like a good solution. I don't think we can get RawHandle navigatable on unix, or is that possible somehow?

[sdroege]

FWIW, I merged the futures commit into master and 1.14 independent of these changes here

[fengalin]

Yes, of course that's the best compromise. Just updated the commit stack with this approach.

Sorry, I wasn't clear about the handles navigation. I meant navigating in the doc as being able to access documentation of the actual handle in the std doc. So you can navigate to the std doc for the handle of the target platform for which the doc was generated, but not for the handle of the other platform (because the std::io::_other_handle_ is not available).

[sdroege]

Thanks, I think this solution is good for now :) I'm planning to release some time later today with the 1.14 branch btw, or tomorrow. In case you have something else that should be merged before that.

[fengalin]

Great! I don't have plans for more commits right now.

[sdroege]

Ok :) Thanks for all your work!

[fengalin]

My pleasure!