Revised docstring style guide.

[stevepiercy]

Linked issue

• Closes Document how to document the order of parameters in docstrings #1618

Description

• Revised how to document parameters in docstrings, specifically their order of appearance and usage of type hints.
• Revised guidance to write docstrings only for a class, and not their __init__ or __new__ methods.

Checklist

• I added a change log entry, following the instructions in Change log entry format.
• I followed icalendar's Artificial intelligence policy and disclosed my Responsible AI use in my commit messages, if applicable.
• I added or updated tests, if applicable.
• I ran and ensured all tests pass locally by following Run tests.
• I added or edited documentation as necessary, both as docstrings to be rendered in the API documentation and narrative documentation, following the Style guide.

[github-actions]

Profile summary:

GitHub user: stevepiercy
🟢 No concerns found with user's profile.
🟢 No concerns found with recent PR activity.
🟢 No concerns found with recent issue activity.

For a more detailed report, run `gh-profiler stevepiercy`.

Full profile

GitHub user: stevepiercy
🟢 No concerns found with user's profile.
   🟢 Account age: 17 years
   🟢 Profile information:
        name: Steve Piercy
        company: Steve Piercy - Website Builder
        blog: https://stevepiercy.com/
        location: Eugene, OR
        bio: Contributor to open source projects icalendar, Plone, Pyramid, and Deform. Everyday cyclist. Backyard farmer. Tree hugger. Living simply.
        mastodon: https://fosstodon.org/@stevepiercy
      Empty fields: email
      Orgs: plone, collective, Pylons, zopefoundation, knop-project, pycalendar

🟢 No concerns found with recent PR activity.
   13 PRs opened in the last 21 days.
      0 opened against repos the user owns.
      13 opened against repos in publicly associated orgs.
      0 opened against external repos.

🟢 No concerns found with recent issue activity.
   13 new issues opened in the last 21 days.
      0 opened in repos the user owns.
      11 opened in repos in publicly associated orgs.
      2 opened in external repos.

   🟢 0 external issues closed as NOT_PLANNED.
   🟢 0 external issues opened with the same title.

[read-the-docs-community]

Documentation build overview

📚 icalendar | 🛠️ Build #33861766 | 📁 Comparing 774263a against latest (926bc02)

  🔍 Preview build  

3 files changed

± 404.html
± contribute/development.html
± contribute/documentation/style-guide.html

[niccokunzmann]

Thanks! I have some ideas :)

[coveralls]

coverage: 98.0%. remained the same — doc-param-order into main

[niccokunzmann]

Todo:

• when Merge constructor docstrings into class docstrings #1622 is merged, we can disable new and init docs
• we can remove the part from the docs about possible docstrings in init and new
• add an issue to test that all init and new methods do not have a docstring, linking to docs and relevant issues in the error message

Can be new issues or split up or part of the doctest.

[stevepiercy]

Todo:

* [ ]  when [Merge constructor docstrings into class docstrings #1622](https://github.com/collective/icalendar/pull/1622) is merged, we can disable new and init docs
* [ ]  we can remove the part from the docs about possible docstrings in init and new
* [ ]  add an issue to test that all init and new methods do not have a docstring, linking to docs and relevant issues in the error message

All that's already in #1620