Documentation tweaks

[pitdicker]

This is one of those things that have been sitting as a half-finished branch for a couple of months...

I would like to tweak the inline/no-inline attributes of re-exports in lib.rs so that the the useful types are better visible than the ones that are rarely needed return types.

Before

After

[codecov]

Codecov Report

Merging #1274 (77bb121) into 0.4.x (22846c9) will increase coverage by 0.00%.
The diff coverage is 0.00%.

@@           Coverage Diff           @@
##            0.4.x    #1274   +/-   ##
=======================================
  Coverage   91.50%   91.50%           
=======================================
  Files          38       38           
  Lines       17313    17314    +1     
=======================================
+ Hits        15843    15844    +1     
  Misses       1470     1470           

Files	Coverage Δ
src/datetime/mod.rs	89.29% <ø> (+0.14%)	⬆️
src/datetime/rustc_serialize.rs	92.72% <ø> (ø)
src/datetime/serde.rs	87.56% <ø> (ø)
src/format/mod.rs	85.04% <ø> (ø)
src/lib.rs	95.58% <ø> (ø)
src/naive/date.rs	96.22% <ø> (ø)
src/naive/datetime/mod.rs	97.63% <ø> (ø)
src/naive/time/mod.rs	96.53% <ø> (ø)
src/offset/local/mod.rs	85.32% <ø> (ø)
src/offset/mod.rs	56.00% <ø> (ø)
... and 2 more

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[pitdicker]

This took a little more effort.

If you don't document a type right at the crate root, it must be in another public module or otherwise it will not be documented:

• I made the round module public, so we can hide the DurationRound trait and co. in there (I don't like that one all 😄).
• SecondsFormat is moved from the private datetime module to public module formatting. Seems like a better place anyway.

And because types such as NaiveDate and NaiveTime now have a copy of their documentation in the main module, old manual links in their methods were broken. I updated them to rust paths (but did not go over all documentation to fix all old-style links, just the ones that were broken).

[djc]

I don't understand the argument put forth in the commit message. What's the rationale for this change?

[pitdicker]

The idea is to highlight the importants traits in the "Traits" section: TimeZone, Offset, Datelike and Timelike.
I don't think DurationRound and SubsecRound are good enough to be part of the list in the main documentation.
We can only hide it in the list if the round module is public.

To say it stronger, in my opinion the DurationRound trait is something that begs for a replacement.

[djc]

Okay, sure, but if that's the goal IMO the other changes to that goal should be in the same commit as that. In general, the first commit here seems too large/unfocused (it probably doesn't help that I'm completely unfamiliar with the semantics of doc(no_inline))...

[pitdicker]

O, sorry. That was only the goal of that commit. No: the goal of the PR was tweaking doc(inline) and doc(no_inline).

If the original module is public:

• a re-export comes under the list "Re-exports".
• doc(inline) on a re-export copies the documentation, so it now lives at two places.

If the original module is private:

• a re-export moves the documentation.
• doc(no_inline) makes the documentation unreachable.

[pitdicker]

In general, the first commit here seems too large/unfocused

I have split it up into three commits.

[pitdicker]

Oops, that means this line does nothing 😄.