Missing documentation

[GeoffClements]

As a new user pulse audio I've been going through the documentation over on the freedesktop site but it's really helpful to see the more Rusty comments and I notice that this crate doesn't have a link to the documents on docs.rs.

This is a shame because the all the necessary doc comments are there they just don't seem to be recognised when doing a cargo publish. I don't know why this is the case, maybe because many of the files begin with /// comments and not //!, but that's just my guess.

I just fried running cargo doc --open on my cloned repo. It runs fine, so I've no idea why cargo publish doesn't do this.

[jnqnfe]

Hi, documentation for older versions of my rust bindings can be found on docs.rs, however docs.rs support is currently broken for newer versions. I presume that is what the problem is here.

As for why it's broken, it's due to a conflict between a docs.rs related hack around a long standing rust compiler issue, and a change made to the quotes crate. Building this create requires the presence of pkg-config and the PulseAudio pkg-config file. In order to give a nice clean error on systems that don't have these requirements, the build scripts of the sys crates perform a pkg-config check. These requirements and this check are unnecessary though for building documentation. In fact the docs.rs build system cannot be expected to fulfil these requirements, so to support docs.rs building my documentation, this check must be disabled when run by docs.rs. Rust version 1.41 introduced the doc feature allowing detection of documentation build mode, which enabled crates like mine to ditch an older hack based around having a feature commonly named dox. However, as discussed here and here the rust compiler does not pass this official doc flag to build scripts, making it impossible for build scripts to detect that they are being run under documentation building mode. We've been waiting for a fix for this deficiency for a few years now. As a work around, crates like mine force use of --cfg doc when run on docs.rs via our cargo.toml files. This simple and neat solution worked fine, until an author of the quotes trait made a change to their crate that broke it (see here). The change they made was to give a simplified view of their macro in documentation, by effectively using a completely different macro than for normal builds. Their crate chooses which copy of the macro to use depending upon presence of the doc feature. That might work fine for building documentation of their own crate, but it seems to completely break crates like mine using this hack to force --cfg doc to cover our build scripts. :/ To restore working docs.rs documentation either the quotes authors need to reverse this change, or I need to go backwards restoring the uglier old dox hack, or we need movement on the rust compiler issue.

[GeoffClements]

Ahh, thanks. Wasn't sure you were aware that the docs being dropped was happening but it's clear you are. Sorry for the noise, I'll close the issue.

[jnqnfe]

Update: I found an easy solution to fix the problem and so I'm happy to say that docs.rs is working again. :)

[GeoffClements]

Oh nice work! This crate will be much more ergonomic for people new to pulseaudio (like me!).

Thank-you.