Docs: the calendar module lacks documentation for several APIs

[erlend-aasland]

But first than documenting these particular method or two, we should decide whether they should be documented at all.

See past issues with the calendar module. There may be requests for undocumented methods, and some of them may even be rejected already. I think this has already been discussed.

Originally posted by @serhiy-storchaka in #108192 (comment)

Linked PRs

• GH-108202: Document calendar exceptions #108398
• [3.12] GH-108202: Document calendar exceptions (GH-108398) #108467
• [3.11] GH-108202: Document calendar exceptions (GH-108398) #108468
• gh-108202: calendar: Document prweek #108466
• GH-108202: Combine documentation of calendar constants #108492
• [3.12] GH-108202: Combine documentation of calendar constants (GH-108492) #108579
• GH-108202: Document calendar's command-line interface #109020
• [3.12] GH-108202: Document calendar's command-line interface (GH-109020) #109030
• [3.11] GH-108202: Document calendar's command-line interface (GH-109020) #109031
• gh-108202: Document calendar.Calendar methods getfirstweekday and setfirstweekday #127579
• gh-108202: calendar: Document TextCalendar methods #127608
• [3.13] gh-108202: Document calendar.TextCalendar formatting helpers (GH-127608) #128440
• [3.12] gh-108202: Document calendar.TextCalendar formatting helpers (GH-127608) #128441
• [3.13] gh-108202: Document calendar.Calendar methods getfirstweekday and setfirstweekday (GH-127579) #128564
• [3.12] gh-108202: Document calendar.Calendar methods getfirstweekday and setfirstweekday (GH-127579) #128565
• gh-108202: Document calendar.Calendar.firstweekday #128566
• [3.13] gh-108202: Document calendar.Calendar.firstweekday (GH-128566) #128579
• [3.12] gh-108202: Document calendar.Calendar.firstweekday (GH-128566) #128580

[AA-Turner]

(status as at 21c0844)

Defined in __all__ but not documented

• IllegalMonthError (GH-108202: Document calendar exceptions #108398)
• IllegalWeekdayError (GH-108202: Document calendar exceptions #108398)
• JANUARY, etc (These are documented as Month.X, but also exist in the module scope) (GH-108202: Combine documentation of calendar constants #108492)
• MONDAY, etc (These are documented as Day.X, but also exist in the module scope) (GH-108202: Combine documentation of calendar constants #108492)

Undocumented classes

• different_locale (should not be documented, helper class)

Undocumented functions

• prweek()
• week()
• format()
• formatstring()

Undocumented methods

Calendar

• Calendar.getfirstweekday()
• Calendar.setfirstweekday()
• Calendar.firstweekday: (gh-108202: Document calendar.Calendar.firstweekday #128566)

TextCalendar

• TextCalendar.prweek() (gh-108202: calendar: Document prweek #108466)
• TextCalendar.formatday() (gh-128317: Document calendar.TextCalendar.formatweek #128353)
• TextCalendar.formatweek()
• TextCalendar.formatweekday()
• TextCalendar.formatweekheader()
• TextCalendar.formatmonthname()

HTMLCalendar

• HTMLCalendar.formatday()
• HTMLCalendar.formatweek()
• HTMLCalendar.formatweekday()
• HTMLCalendar.formatweekheader()
• HTMLCalendar.formatmonthname()

Undocumented attributes

• EPOCH (should not be documented, of no use)
• mdays (should not be documented, of no use)

Undocumented miscellany

• python -m calendar (main()) (GH-108202: Document calendar's command-line interface #109020)

A

[AA-Turner]

I think at the least we ought document IllegalMonthError and IllegalWeekdayError, I'll open a PR shortly.

A

[erlend-aasland]

I removed the easy label. Adding docs for the calendar module is controversial. Please read the OP and #108202 (comment).