Add comprehensive docstrings to core modules

[jjjake]

Summary

• Add missing docstrings to core library modules for improved documentation
• Standardize docstring format using Sphinx-style (:param:, :returns:, :raises:)
• Convert Google-style docstrings (Args/Returns) to Sphinx-style for consistency
• Fix pre-existing mypy type error in config.py
• Fix docs index page issues

Changes

utils.py

• deep_update() - Document recursive dict merging
• validate_s3_identifier() - Document identifier validation rules
• needs_quote() - Document URI quoting check
• norm_filepath() - Document path normalization
• get_md5() - Document MD5 hash calculation
• chunk_generator() - Document file chunk generation
• IterableToFileAdapter class - Document file-like wrapper for iterables
• IdentifierListAsItems class - Add param documentation
• get_s3_xml_text() - Document S3 XML error parsing
• get_file_size() - Document file size determination
• recursive_file_count_and_size() - Complete param documentation
• remove_none() - Document None value removal
• is_valid_metadata_key() - Document metadata key validation
• parse_dict_cookies() - Document cookie string parsing
• is_valid_email() - Document email validation
• is_windows() - Document platform detection
• Convert sanitize_* functions from Args/Returns to :param:/:returns:

account.py

• Convert all methods from Google-style to Sphinx-style:
  • _post_api_request(), from_account_lookup(), _fetch_account_data_from_api()
  • from_json(), lock(), unlock(), to_dict()

api.py

• get_tasks() - Add missing param docs (config, config_file, archive_session, etc.)
• search_items() - Fix incorrect secure reference, add archive_session and config params
• configure() - Add missing config_file and host param docs

session.py

• get_connection_info() - Document return dict structure
• rebuild_auth() - Explain redirect authentication handling
• s3_is_overloaded() - Document S3 rate limit checking
• get_tasks_api_rate_limit() - Document Tasks API rate limits
• send() - Add docstring for HTTPS security handling

item.py

• BaseItem class - Add class-level docstring
• load(), refresh() - Document metadata loading
• get_files() - Document file filtering options
• Review methods (get_review, index_review, noindex_review, delete_review, review)
• Flag methods (get_flags, add_flag, delete_flag)

config.py

• get_auth_config() - Document authentication flow
• write_config_file() - Document config file writing
• parse_config_file() - Document config file search order
• get_config() - Document config merging precedence
• Fix mypy error: convert bool to str in config.set() call

files.py

• BaseFile class - Add class docstring with attribute documentation

search.py

• Search.__init__() - Document all parameters
• iter_as_results(), iter_as_items() - Document iteration methods

iarequest.py

• S3Request class - Document IA-S3 upload request handling
• MetadataRequest class - Document metadata modification requests
• prepare_patch() - Add docstring for JSON Patch creation
• prepare_target_patch() - Add docstring for target path patching
• prepare_files_patch() - Add docstring for file-level metadata patching
• prepare_metadata() - Convert to Sphinx-style
• _process_indexed_keys() - Convert to Sphinx-style

catalog.py

• get_rate_limit() - Document rate limit checking

auth.py

• S3Auth - Improve docstring with usage example
• S3PostAuth - Document POST authentication scheme

docs/source/index.rst

• Fix broken Installation link (:ref:install → `:ref:`installation)
• Fix heading hierarchy (Setup & Configuration same level as siblings)
• Move Authors to top-level section
• Add Module Index to Indices and tables

docs/source/conf.py

• Update copyright to 2015-2026

Test plan

• All pre-commit hooks pass (ruff, black, mypy, codespell)
• All tests pass (201 passed, 37 skipped)
• Documentation builds successfully with cd docs && make html

🤖 Generated with Claude Code