Lint missing docs in icu_datetime

[gregtatum]

This is an initial stab at #686 for icu_datetime. There are still lots of docs to write here.

[codecov-commenter]

Codecov Report

Merging #725 (b6df5ad) into main (1f4a950) will decrease coverage by 0.02%.
The diff coverage is 0.00%.

@@            Coverage Diff             @@
##             main     #725      +/-   ##
==========================================
- Coverage   74.68%   74.66%   -0.03%     
==========================================
  Files         178      178              
  Lines       10710    10712       +2     
==========================================
- Hits         7999     7998       -1     
- Misses       2711     2714       +3     

Impacted Files	Coverage Δ
components/datetime/src/date.rs	49.18% <0.00%> (-0.82%)	⬇️
components/datetime/src/lib.rs	100.00% <ø> (ø)
components/datetime/src/provider/time_zones.rs	18.18% <ø> (ø)
experimental/provider_ppucd/src/parse_ppucd.rs	92.99% <0.00%> (-0.14%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1f4a950...b6df5ad. Read the comment docs.

[coveralls]

Pull Request Test Coverage Report for Build cce347fb872c76e3729b471c5a9707f5ad4398c5-PR-725

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 12 unchanged lines in 4 files lost coverage.
• Overall coverage decreased (-0.008%) to 75.018%

---

Files with Coverage Reduction	New Missed Lines	%
components/datetime/src/options/length.rs	1	25.0%
experimental/provider_ppucd/src/parse_ppucd.rs	1	93.28%
components/datetime/src/options/components.rs	4	77.39%
components/datetime/src/date.rs	6	50.0%

Totals
Change from base Build f52429e0ca3505eee821bd57218c20a80013283a:	-0.008%
Covered Lines:	9585
Relevant Lines:	12777

---

💛 - Coveralls

[sffc]

I think we should merge this with the docs Greg wrote, even if they aren't comprehensive. It's a step in the right direction, and better to be merged than to sit in a PR.

[jira-pull-request-webhook]

Notice: the branch changed across the force-push!

• components/datetime/src/date.rs is different
• components/datetime/src/datetime.rs is now changed in the branch
• components/datetime/src/format/zoned_datetime.rs is now changed in the branch
• components/datetime/src/lib.rs is different
• components/datetime/src/options/components.rs is now changed in the branch
• components/datetime/src/options/length.rs is now changed in the branch
• components/datetime/src/options/preferences.rs is now changed in the branch
• components/datetime/src/pattern/error.rs is now changed in the branch
• components/datetime/src/provider/gregory.rs is now changed in the branch
• components/datetime/src/provider/mod.rs is different
• components/datetime/src/provider/time_zones.rs is different
• components/datetime/src/skeleton.rs is now changed in the branch

View Diff Across Force-Push

~ Your Friendly Jira-GitHub PR Checker Bot

[gregtatum]

I finished either filling in the docs or adding suppressions.

[nordzilla]

LGTM, pending a few minor comments.

[nordzilla]

Question

This has a doc comment. Why is the linter saying it's missing?

[gregtatum]

All fields require doc comments. Here the comments wouldn't add any more meaning.

e.g.

/// ...
pub enum IsoWeekday {
    /// This is a Monday!
    Monday = 1,
    ....
}

[nordzilla]

Thought

I've been thinking a bit about our documentation style. Manually linking these keywords can be very verbose, tedious, and pain to maintain if the paths ever change.

Question

How do you feel about adding a doc-only use declaration to the top of the file?

e.g.

#[cfg(doc)]
use {
    crate::provider::{
        gregory::{DatePatternsV1, DateSymbolsV1},
        time_zones::{
            ExemplarCitiesV1, MetaZoneGenericNamesLongV1, MetaZoneGenericNamesShortV1,
            MetaZoneSpecificNamesLongV1, MetaZoneSpecificNamesShortV1, TimeZoneFormatsV1,                           
        },  
    },  
    icu_provider::prelude::ResourceKey,
};

Then your comment could just be

/// A [`ResourceKey`] to [`DatePatternsV1`].

We would only need to re-link it if we wanted to explicitly rename it, and even then there are no paths to deal with, so it still looks clean:

/// A [`ResourceKey`] to [`DatesV1`](DatePatternsV1).

I think this style would really unclutter our documentation. I think it's nice to have all the doc-only dependencies in one spot. I think it's also nice that it gives readers of the file some intuition of related modules, even though they aren't directly included as dependencies when building the code itself.

[gregtatum]

Ah that would be great, and they should hopefully be checked by the compiler.

[jira-pull-request-webhook]

Notice: the branch changed across the force-push!

• components/datetime/src/date.rs is different
• components/datetime/src/provider/mod.rs is different

View Diff Across Force-Push

~ Your Friendly Jira-GitHub PR Checker Bot

[dminor]

lgtm!