Implementation Plan (Issue #19)

Implementation Plan for Issue #19: Add Comprehensive Docstrings to Public Interface

Overview

Add comprehensive Fortran docstrings to all public procedures in src/fortplot.f90 to improve API documentation and usability.

Documentation Standards

Fortran Docstring Format

Based on existing patterns in the codebase and FORD documentation standards:

subroutine procedure_name(arg1, arg2, arg3)
    !! Brief description of the procedure
    !!
    !! Detailed description explaining the purpose, behavior,
    !! and any important implementation details.
    !!
    !! Arguments:
    !!   arg1: Description of first argument [units/range]
    !!   arg2: Description of second argument (optional)
    !!   arg3: Description with valid values ('option1', 'option2')
    !!
    !! Examples:
    !!   ! Basic usage example
    !!   call procedure_name(x, y)
    !!   
    !!   ! Advanced usage with options
    !!   call procedure_name(x, y, arg3='option2')
    !!
    !! Notes:
    !!   - Important usage notes or caveats
    !!   - Performance considerations
    !!
    !! See Also:
    !!   related_procedure, other_procedure

Documentation Components Required

  1. Brief Description (mandatory)
  2. One-line summary of the procedure's purpose

  3. Should be concise and action-oriented

  4. Detailed Description (for complex procedures)

  5. Extended explanation of functionality

  6. Use cases and context

  7. Arguments Section (mandatory)

  8. Document ALL arguments including optionals
  9. Include data types, units, valid ranges
  10. Specify default values for optional arguments

  11. List valid options for string arguments

  12. Examples Section (for key procedures)

  13. Show basic usage pattern
  14. Include advanced usage when applicable

  15. Use realistic variable names

  16. Notes Section (when needed)

  17. Performance considerations
  18. Backend-specific behavior

  19. Important limitations or caveats

  20. See Also Section (for related procedures)

  21. Cross-reference related functionality
  22. Help users discover similar features

Procedures Requiring Documentation

Category 1: Core Plotting Functions (HIGH PRIORITY)

Complete documentation with examples needed:

  1. plot - Has basic docs, needs examples and argument details
  2. scatter - Has good docs with examples (reference standard)
  3. contour - Has basic docs, needs enhancement
  4. contour_filled - Has basic docs, needs examples
  5. pcolormesh - Minimal docs, needs full documentation
  6. streamplot - Minimal docs, needs full documentation
  7. errorbar - Has basic docs, needs examples
  8. boxplot - Minimal docs, needs full documentation
  9. bar/barh - Minimal docs, needs full documentation
  10. hist/histogram - Minimal docs, needs full documentation

Category 2: Figure Management (MEDIUM PRIORITY)

Need complete documentation:

  1. figure - Has basic docs, needs argument details
  2. show/show_viewer - Minimal docs, needs full documentation
  3. savefig - Has basic docs, needs format details

Category 3: Axis and Label Functions (MEDIUM PRIORITY)

Need enhancement:

  1. xlabel/ylabel - Minimal docs, needs LaTeX support notes
  2. title - Minimal docs, needs formatting details
  3. legend - Minimal docs, needs location options
  4. xlim/ylim - No docs, needs full documentation
  5. set_xscale/set_yscale - No docs, needs scale options

Category 4: Add Functions (LOW PRIORITY)

Mirror documentation from primary functions:

  1. add_plot - Mirror from plot
  2. add_contour - Mirror from contour
  3. add_contour_filled - Mirror from contour_filled
  4. add_pcolormesh - Mirror from pcolormesh
  5. add_errorbar - Mirror from errorbar
  6. add_3d_plot - Needs full documentation
  7. add_surface - Needs full documentation
  8. add_scatter - Mirror from scatter

Category 5: Utility Functions (LOW PRIORITY)

  1. set_line_width - No docs, needs documentation
  2. set_ydata - No docs, needs documentation
  3. ensure_global_figure_initialized - Has minimal docs

Implementation Strategy

Phase 1: Document Core Plotting Functions

Priority: HIGH - Focus on most-used functions first - Use scatter documentation as template - Include practical examples - Document all optional arguments

Phase 2: Document Figure Management

Priority: MEDIUM
- Document backend auto-detection in savefig - Explain blocking parameter behavior - Document viewer functionality

Phase 3: Document Axis/Label Functions

Priority: MEDIUM - Document LaTeX support where applicable - List all valid location options for legend - Document scale types (linear, log, symlog)

Phase 4: Document Add Functions

Priority: LOW - Reference main function documentation - Note differences if any - Keep consistent with primary functions

Phase 5: Document Utility Functions

Priority: LOW - Focus on user-facing utilities - Document internal helpers minimally

Documentation Template Examples

Example 1: Enhanced plot documentation

subroutine plot(x, y, label, linestyle)
    !! Add a line plot to the global figure (pyplot-fortran compatible)
    !!
    !! Creates a 2D line plot with optional styling. Supports both
    !! matplotlib-style format strings and explicit style parameters.
    !!
    !! Arguments:
    !!   x: X-axis data array
    !!   y: Y-axis data array (same size as x)
    !!   label: Legend label for this plot (optional)
    !!   linestyle: Format string for line and marker style (optional)
    !!             Supports matplotlib format: '[color][marker][line]'
    !!             Examples: 'r-' (red solid), 'b--o' (blue dashed with circles),
    !!                      'g:' (green dotted), 'ko' (black circles only)
    !!
    !! Examples:
    !!   ! Basic line plot
    !!   call plot(x, y)
    !!   
    !!   ! Plot with label for legend
    !!   call plot(x, y, label='Temperature')
    !!   
    !!   ! Red dashed line with square markers
    !!   call plot(x, y, label='Data', linestyle='r--s')
    !!
    !! Notes:
    !!   - Automatically initializes global figure if needed
    !!   - Use savefig() to save or show() to display
    !!
    !! See Also:
    !!   add_plot, scatter, errorbar

Example 2: Enhanced savefig documentation

subroutine savefig(filename, blocking)
    !! Save the global figure to file (backend auto-detected from extension)
    !!
    !! Automatically selects the appropriate backend based on file extension.
    !! Supports PNG, PDF, and ASCII text formats.
    !!
    !! Arguments:
    !!   filename: Output filename with extension
    !!            '.png' - Raster image (default)
    !!            '.pdf' - Vector graphics
    !!            '.txt' - ASCII art representation
    !!   blocking: Wait for user input after save (optional, default: false)
    !!            Useful for keeping plot windows open
    !!
    !! Examples:
    !!   ! Save as PNG image
    !!   call savefig('plot.png')
    !!   
    !!   ! Save as PDF and wait for user
    !!   call savefig('figure.pdf', blocking=.true.)
    !!   
    !!   ! Save as ASCII art
    !!   call savefig('chart.txt')
    !!
    !! Notes:
    !!   - PNG backend requires zlib support
    !!   - PDF backend generates vector graphics
    !!   - ASCII backend works in terminal environments
    !!   - File is overwritten if it exists

Risk Assessment

Technical Risks

  1. Documentation Drift (MEDIUM)
  2. Risk: Documentation becomes outdated as code evolves
  3. Mitigation: Enforce documentation updates in PR reviews

  4. Mitigation: Add documentation tests to verify examples compile

  5. Over-Documentation (LOW)

  6. Risk: Too verbose documentation reduces readability
  7. Mitigation: Follow KISS principle - be concise but complete

  8. Mitigation: Use examples instead of lengthy descriptions

  9. Inconsistent Style (LOW)

  10. Risk: Different documentation styles across procedures
  11. Mitigation: Use template and review for consistency
  12. Mitigation: Reference scatter documentation as gold standard

Schedule Risks

  1. Scope Creep (MEDIUM)
  2. Risk: Adding new features while documenting
  3. Mitigation: Document existing functionality only

  4. Mitigation: File separate issues for improvements

  5. Time Estimation (LOW)

  6. Risk: Underestimating documentation effort
  7. Mitigation: Start with high-priority functions
  8. Mitigation: Incremental documentation acceptable

Success Criteria

  1. All public procedures in fortplot.f90 have at minimum:
  2. Brief description

  3. Arguments section with all parameters documented

  4. Core plotting functions have:

  5. Detailed descriptions
  6. Multiple examples

  7. Notes on backend-specific behavior

  8. Documentation follows consistent format across all procedures

  9. Examples are tested and working

  10. Cross-references help users discover related functionality

Testing Strategy

  1. Compilation Testing
  2. Ensure all example code in docstrings compiles

  3. Create test program that exercises all examples

  4. Documentation Generation

  5. Verify FORD can process all docstrings

  6. Check generated HTML documentation

  7. User Testing

  8. Have new users try to use API with only docstring help
  9. Gather feedback on clarity and completeness

Estimated Timeline

  • Phase 1 (Core Functions): 2 hours
  • Phase 2 (Figure Management): 1 hour
  • Phase 3 (Axis/Labels): 1 hour
  • Phase 4 (Add Functions): 1 hour
  • Phase 5 (Utilities): 30 minutes
  • Testing and Review: 1.5 hours

Total Estimate: 7 hours

References

  • Existing scatter documentation (good example)
  • FORD documentation standards
  • Matplotlib API documentation patterns
  • pyplot-fortran interface design