These documents are still things that can become out of date. Anything of this nature can be in a source file somewhere, even if it’s a giant overview comment in one of the main files.
I do think it’s fine to create pretty docs from source comments or generate pictures from graph descriptions, etc. Every generated page should clearly state where it came from though (e.g. revision number and date).
Frankly I don’t like having only an API doc without the implementation. Code should be open-source to those using it, under NDA if necessary. When I need to rely on hidden implementations from Apple, etc. I routinely have to waste time discovering things simply not working as described. Meaning, their pretty docs are out of sync with reality and it wastes significant time to find this out the hard way.
I do think it’s fine to create pretty docs from source comments or generate pictures from graph descriptions, etc. Every generated page should clearly state where it came from though (e.g. revision number and date).
Frankly I don’t like having only an API doc without the implementation. Code should be open-source to those using it, under NDA if necessary. When I need to rely on hidden implementations from Apple, etc. I routinely have to waste time discovering things simply not working as described. Meaning, their pretty docs are out of sync with reality and it wastes significant time to find this out the hard way.