Waterloo Docstrings¶
Contents:
- 1. Introduction
- 1.1. About Waterloo Docstrings
- 1.2. Why normative documentation?
- 1.3. Normativity keywords and their scope
- 1.4. Recipients and output formats
- 1.5. Basic principles of Waterloo Docstrings
- 1.6. Scope and limits of the principles
- 1.7. Project status
- 1.8. Dependencies
- 1.9. Introductory examples
- 1.10. Convenience: module and class stack
- 1.11. Project Name
- 2. Getting Started
- 3. Docstrings - minimal and full examples
- 3.1. Module docstrings – minimal example
- 3.2. Module docstrings – full example
- 3.3. Class docstrings – minimal example
- 3.4. Class docstrings – full example
- 3.5. Function docstrings – minimal example
- 3.6. Function and method docstrings – intermediate example
- 3.7. Interlude – Docstring for inherited methods
- 3.8. Function docstrings – full example
- 4. Examples
- 5. Docstring format
- 5.1. Definitions
- 5.2. Terminology
- 5.3. Specification conventions
- 5.4. Meta
- 5.5. Rule taxonomy
- 5.6. The structure of Waterloo docstrings
- 5.7. Conventions
- 5.8. Building the AST
- 5.9. Inline markup in free-form content
- 5.10. Rules not bound to a particular section
- 5.11. Normativity keyword handling
- 5.12. Sections and subsections
- 5.13. Rules for exceptions not supposed to occur
- 5.14. Coverage rules and intended workflow
- 5.15. Scopes and visibility
- 5.16. Rationale: SSoT for Normative Statements
- 5.17. Distinction
DescriptionvsNotes - 5.18. Distinction
generalvsinvariants - 5.19. Distinction
ensuresvsinvariants
- 6. Tools
- 7. Overview: I/O Layers
- 8. The JSON I/O Layer
- 9. The HTML Output Layer
- 10. Model Context Protocol
- 11. Reference - Rendering Showcase
- 11.1. Module
docitem- 11.1.1. Fundamental helpers
- 11.1.1.1.
get_obj_name - 11.1.1.2.
get_obj_fully_qualified_name - 11.1.1.3.
get_obj_path - 11.1.1.4.
get_obj_docstring - 11.1.1.5.
get_obj_annotations - 11.1.1.6.
is_obj_module - 11.1.1.7.
is_obj_class - 11.1.1.8.
is_obj_function - 11.1.1.9.
is_obj_method_like - 11.1.1.10.
is_obj_documentable - 11.1.1.11.
is_obj_named_value - 11.1.1.12.
get_func_obj_from_callable
- 11.1.1.1.
- 11.1.2. Typechecking helpers
- 11.1.3. Tokenizer functions
- 11.1.4. AST properties
- 11.1.5. Per-object validators
- 11.1.6. Coverage validators
- 11.1.6.1.
validate_class_class_coverage - 11.1.6.2.
validate_class_method_coverage - 11.1.6.3.
validate_class_constant_coverage - 11.1.6.4.
validate_class_coverage - 11.1.6.5.
validate_module_class_coverage - 11.1.6.6.
validate_module_function_coverage - 11.1.6.7.
validate_module_type_coverage - 11.1.6.8.
validate_module_constant_coverage - 11.1.6.9.
validate_module_variable_coverage - 11.1.6.10.
validate_module_coverage
- 11.1.6.1.
- 11.1.7. Additional helpers
- 11.1.8. Diagnostics helpers
- 11.1.8.1.
explain_try_self_for_section - 11.1.8.2.
explain_try_self_for_subsection - 11.1.8.3.
render_allowed_identifier - 11.1.8.4.
render_allowed_identifiers - 11.1.8.5.
render_base_method_docstring_details - 11.1.8.6.
render_base_method_reference_details - 11.1.8.7.
render_constant_reference_details - 11.1.8.8.
render_deduplicated_identifiers - 11.1.8.9.
render_definition_reference_details - 11.1.8.10.
render_exactly_one_identifier_details - 11.1.8.11.
render_expected_identifier - 11.1.8.12.
render_expected_snippet - 11.1.8.13.
render_identifier_lines - 11.1.8.14.
render_inherited_definition_details - 11.1.8.15.
render_listed_object_missing_details - 11.1.8.16.
render_missing_entry_details - 11.1.8.17.
render_name_object_consistency_details - 11.1.8.18.
render_named_value_reference_details - 11.1.8.19.
render_normative_section_details - 11.1.8.20.
render_normativity_keyword_details - 11.1.8.21.
render_overview_missing_member_details - 11.1.8.22.
render_overview_requires_section_details - 11.1.8.23.
render_parameter_signature_details - 11.1.8.24.
render_profile_mismatch_details - 11.1.8.25.
render_scope_relation_details - 11.1.8.26.
render_see_also_reference_details - 11.1.8.27.
render_source_snippet - 11.1.8.28.
render_suggestion - 11.1.8.29.
render_type_reference_details - 11.1.8.30.
render_unique_identifiers
- 11.1.8.1.
- 11.1.9. Enum classes
- 11.1.10. Helper classes
- 11.1.11. Base classes
- 11.1.12. Preamble node classes
- 11.1.13. Contract node classes
- 11.1.13.1.
docitem_constructor - 11.1.13.2.
docitem_general - 11.1.13.3.
docitem_invariants - 11.1.13.4.
docitem_requires - 11.1.13.5.
docitem_ensures - 11.1.13.6.
docitem_traits - 11.1.13.7.
docitem_contract_module - 11.1.13.8.
docitem_contract_class - 11.1.13.9.
docitem_contract_method - 11.1.13.10.
docitem_class_overview_entry
- 11.1.13.1.
- 11.1.14. Related objects node classes
- 11.1.14.1.
docitem_class_overview - 11.1.14.2.
docitem_public_classes - 11.1.14.3.
docitem_public_functions - 11.1.14.4.
docitem_public_methods - 11.1.14.5.
docitem_public_types_entry - 11.1.14.6.
docitem_public_types - 11.1.14.7.
docitem_public_assignables_entry - 11.1.14.8.
docitem_public_assignables_base - 11.1.14.9.
docitem_method_overview_entry - 11.1.14.10.
docitem_method_overview - 11.1.14.11.
docitem_function_overview_entry - 11.1.14.12.
docitem_function_overview
- 11.1.14.1.
- 11.1.15. Other sections node classes
- 11.1.15.1.
docitem_returns - 11.1.15.2.
docitem_parameters_entry - 11.1.15.3.
docitem_parameters - 11.1.15.4.
docitem_raises_entry - 11.1.15.5.
docitem_raises - 11.1.15.6.
docitem_derived_from - 11.1.15.7.
docitem_factory_functions - 11.1.15.8.
docitem_factory - 11.1.15.9.
docitem_definitions_entry - 11.1.15.10.
docitem_inherited_defitems - 11.1.15.11.
docitem_definitions - 11.1.15.12.
docitem_terminology_entry - 11.1.15.13.
docitem_terminology - 11.1.15.14.
docitem_description - 11.1.15.15.
docitem_notes_entry - 11.1.15.16.
docitem_notes - 11.1.15.17.
docitem_see_also
- 11.1.15.1.
- 11.1.16. Top-level node classes
- 11.1.17. Factories
- 11.1.1. Fundamental helpers
- 11.2. Module
docitem_sphinx - 11.3. Module
docitem_convert - 11.4. Module
docitem_genutil - 11.5. Pygments Lexer
- 11.6. Output layer HTML5
- 11.1. Module
- 12. Test: Flow control in freeform sections
- 13. Test: Scopes
- 14. Test: Pygments lexer showcase
- 15. Legal Notes
