Fix current docs build issues

[JosephLenton]

Apache Iceberg Rust version

None

Describe the bug

There are a number of issues in the current docs build. This includes:

• Trailing triple backslash on it's own at the end of a doc comment (it's opened and never closed).
• Links to specs which are not clickable.
• References to internal APIs that are not accessible.

I propose fixing up the docs to fix these niggling issues. Making the links clickable would be a nice QoL improvement.

To Reproduce

• There are warnings outputted here from the last docs.rs release build https://docs.rs/crate/iceberg/latest/builds/3912412
• Running cargo doc --no-deps also displays the errors.

Expected behavior

• There should be no errors or warnings when build the docs.

Willingness to contribute

I can contribute a fix for this bug independently

[dannycjones]

Thanks for opening this!

In addition to addressing the current warnings, it would be great to have something in CI warn/block when these are introduced so we don't need to do this work again in the future. This would be great as a follow-up PR, from yourself or any contributor!

[JosephLenton]

Hey @dannycjones , I'd be happy to do that as a followup. I wasn't sure how far you'd want me to go with cleaning this up so I started small.

I'll address those comments of yours on the PR!