.github/workflows: Deny cargo doc warnings in CI

[ddimaria]

Description

• Update CI to fail on warnings
• Fix all warnings

Links to any relevant issues

Fixes #2914

Open Questions

I'm assuming that it's OK to document private items as it was already specified in the RUSTDOCFLAGS --document-private-items directive. Warnings are still generated with this turned on. To turn off the warnings (in swarm), I added #![allow(rustdoc::private_intra_doc_links)] to lib.rs.

warning: public documentation for `max_negotiating_inbound_streams` links to private item `PoolConfig::with_max_negotiating_inbound_streams`
    --> swarm/src/lib.rs:1373:15
     |
1373 |     /// See [`PoolConfig::with_max_negotiating_inbound_streams`].
     |               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ this item is private
     |
     = note: this link will resolve properly if you pass `--document-private-items`

Change checklist

• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• A changelog entry has been made in the appropriate crates

[thomaseizinger]

Thanks for working on this!

One question.

[thomaseizinger]

I am not sure if it makes sense to allow this. Do the offending links work on docs.rs? Because if not, then there isn't really much of a point I think.

I'd be in favor of rewriting the docs instead.

@mxinden Thoughts?

[mxinden]

I'd be in favor of rewriting the docs instead.

I would be in favor of this as well.

[ddimaria]

The links show up in docs.rs, though the links do not work because the connection and connection/pool modules are private, so completely agree on the doc rewrite (assuming making connection and connection/pool public isn't a good option). Links to the offending documentation:

• https://github.com/libp2p/rust-libp2p/blob/master/swarm/src/dial_opts.rs#L124-L129
• https://github.com/libp2p/rust-libp2p/blob/master/swarm/src/dial_opts.rs#L198-L203
• https://github.com/libp2p/rust-libp2p/blob/master/swarm/src/lib.rs#L1371-L1377

I can lift the doc comments from the referenced functions and replace the private links with them, though this is not DRY, so it adds to the doc-update burden. Thoughts @thomaseizinger ?

[thomaseizinger]

I'd suggest we simply remove the docs from the non-public items and put them on the public ones. In other words, inline the documentation we are currently referring to and deleting it from there!

[ddimaria]

This is done, though I left the documentation in the private functions alone as it looked out of place with the other items documented. It may be out of scope for this PR, but it's worth considering changing /// to // documentation in private items.

[mxinden]

Thanks @ddimaria for the help here.

[mxinden]

I'd be in favor of rewriting the docs instead.

I would be in favor of this as well.

[thomaseizinger]

Awesome, thank you!

[ddimaria]

Awesome, thank you!

Thank you @thomaseizinger! Do you need to approve the workflow (first time contributor)?

First-time contributors need a maintainer to approve running workflows. Learn more. 9 expected checks