Source code docs: documenting crucial functions that aren't documented, making docs clearer

[josephsl]

Hi,

Continuing from #6589:

In addition to code cleanup, I'd like to propose that we do something about source code docs (function docstrings, ePyDoc issues, etc.). Specifically:

• There are some crucial functions used in NVDA Core and add-ons that aren't documented ( for instance, text infos isn't documented well).
• Truly removing code that's listed as deprecated.
• Providing up to date examples.
• If possible, in dev docs collection (not the HTML but module docs), we should have an intro page if possible that is sort of a carbon copy of the source code readme file.
• Other enhancements to make the code docs the best in the business, easy for newbies to understand, and has room for extensions.

Thanks.

[jcsteh]

Documentation improvements are welcome, but I don't think a broad issue is useful (since it's an ongoing process). Also, a massive PR is not ideal. I think smaller chunks is going to be a better path. For example, there could be a PR which improves TextInfo documentation.

[feerrenrut]

I would advise against removing code as part of a bigger issue. It is more likely to hide mistakes, and make it harder to consider whether it truly is safe to remove.
Updating code docs is a great idea, but as @jcsteh mentioned smaller change sets are better. It makes it easier to review and check for correctness.

Since its unlikely this will get done internally, I'll set this as priority 4. Happy to accept a PR for these changes.

[josephsl]

Hi,

2024 update: source code docs situation is getting better. In particular, asking developers to add docs as part of pull requests (when introducing new functions/classes) is giving us improved documentation (ultimately to be generated by Sphinx). We might as well convert this into a discussion.

Thanks.