Does every API need a guide document?

I notice the first few merged PRs have been about updating documentation. Is it necessary for every new API to have include both documentation comments and a markdown guide document?

Personally I find the Swift documentation comment format very readable on its own, and there is some value for those wishing to learn about algorithms by having it next to code.

Is there some other purpose for these guide documents? Could we maybe generate them from the documentation comments?

1 Like

Another role the Guides play is to record a brief justification behind the design and naming of the APIs. I think this is really valuable to capture for each new addition.


Right — each symbol should have documentation that explains its semantics and usage, while the guide documents can cover the intent behind the algorithm and the relationships to other algorithms in the package and the standard library, as well as to similar operations in other languages.