gh-108202: calendar: Document TextCalendar methods

[StanFromIreland]

#108202

• Issue: Docs: the calendar module lacks documentation for several APIs #108202

---

📚 Documentation preview 📚: https://cpython-previews--127608.org.readthedocs.build/

[ZeroIntensity]

Some initial comments. (I'll tag Erlend again once I consider this ready from a triage standpoint.)

It's probably worth converting the phrase "string representation" into a reference to the str class.

[ZeroIntensity]

Ok, I'll refrain from nitpicking. I don't know enough about calendar to give this a green check, so I'll just tag Erlend.

[eendebakpt]

@StanFromIreland I approved the PR, but it takes the approval of a core developer before this can be merged. It is holiday season, so it could take some time

[ZeroIntensity]

This has conflicts now.

[StanFromIreland]

@ZeroIntensity I have asked @hugovk and @erlend-aasland what to do as they seem to have forgotten about this PR.

[hugovk]

Sorry for creating a merge conflict. Can you resolve it? Use whatever text is the better, it doesn't necessarily have to be mine, or combine them.

(Remember to try and keep new text within 80 chars wide: https://devguide.python.org/documentation/markup/#use-of-whitespace)

[StanFromIreland]

@hugovk It has been resolved. Please check for duplicate PRs in the future.

[erlend-aasland]

@StanFromIreland: Please try to keep your PRs focused; that is, one change per PR. This PRs title says the change is to document some methods which are missing documentation. But, in addition you are also tweaking formatting and adding new markups. Multiple types of changes makes reviewing, backporting, and bisecting (for code changes) harder.

Please restrict your PR to one change, and one change only.

[picnixz]

I prefer "string" over the "str" type so please revert them but only in a single commit so that, if other reviewers want to add them back, you can just revert that commit.

[ZeroIntensity]

I prefer "string" over the "str" type

I don't have much of a preference, I'm happy with just the phrase "string" as well.

[picnixz]

It's mostly because the currently documented methods use "string" (without "representation") so I think it's better to be consistent. And because, "a string" is better read than "a str" (even if there is a markup, it's still an incomplete word)

[StanFromIreland]

@erlend-aasland All done now. In the future do you prefer a PR for every function like hugokvs maybe it is easier to review?

[erlend-aasland]

No, do not create one PR for every function. Just don't mix different types of changes in a PR (nor in an issue). This is all explained in clear text in the devguide.

[StanFromIreland]

@erlend-aasland ok. Is this PR ok for you then? Are there any other changes you want before you review? This PR was originally focused on just the functions but then expanded with suggestions from other reviewers, I have reverted all of them.