search

creachadair / imath

Arbitrary precision integer and rational arithmetic library
Other
131 stars 20 forks source link

Consolidate and improve the legibility of API documentation #30

Closed creachadair closed 5 years ago

creachadair commented 5 years ago

The API documentation for IMath is currently separate from the code: The comments in, e.g., imath.h are terse and lack detail, and the "real" documentation is in doc.md. This makes it harder for someone reading the code to find what they need, and means code-browsing tools have no good way to display nice assistive features like hovercards.

I'd like to move the docs back into the header file, but also continue to support the doc.md file, which provides context. This would be a nice case for a literate program, but I think that is more machinery than I really want to pull in: The source files should be compilable in themselves, without a bunch of tools to extract and recompose them for the compiler.

So I think there are two action items here:

  1. [x] Move the API documentation into header comments.
  2. [x] Generate doc.md from a template that includes the header comments.

The net result should be that doc.md remains useful, and becomes mechanically updatable, with the source of truth being switched back to the source code where—arguably—it should have been all along.