relude icon indicating copy to clipboard operation
relude copied to clipboard

Fix documentation inheritance for extension functions (#355)

Open johnhaley81 opened this issue 8 months ago • 0 comments

Summary

  • Enhances documentation injection script to better identify extension functions
  • Groups functions by their source extension module
  • Adds extension module names to improve discoverability

Problem

As described in #355, when using include statements with module functors in ReasonML/OCaml, the documentation from extension modules is lost in the generated odoc documentation. This makes it difficult for users to understand what functions are available from typeclass extensions.

Solution

This PR enhances the documentation injection script to:

  1. Group functions by extension: Functions are now clearly grouped under their source extension module (e.g., "Functions from Monad Extension")
  2. Add brief descriptions: Each documented function includes its first line of documentation
  3. Universal injection: Documentation is injected into all modules that include extensions
  4. Improved validation: Better handling of injection markers and HTML validation

Limitations

Due to odoc's limitations with include statements, we cannot inject the full documentation comments for individual functions. The functions appear in the documentation but without their detailed descriptions. This is a fundamental limitation of how odoc processes include statements - it doesn't follow them to pull documentation from the source modules.

Test Plan

  • [x] Run make docs to build documentation with injection
  • [x] Verify functions appear grouped by extension in HTML docs
  • [x] Check that extension module names are visible
  • [x] Ensure build and tests still pass
  • [x] Validate HTML documentation is generated correctly

Example

In the generated documentation for Relude.Option, functions from the Monad extension now appear grouped together with a clear indication of their source:

Functions from Monad Extension
- flatMap: Flipped version of bind
- flatten: Flattens a nested monadic structure
- unless: Runs a monadic effect if the condition is false
...

Fixes #355

🤖 Generated with Claude Code

johnhaley81 avatar Aug 13 '25 04:08 johnhaley81