karwa
commented
4 years ago I don't know where that conversation is.
Swift has an official documentation comment style which is a kind of markdown and understood by the compiler. This has lots of benefits: for one thing, it's less likely to go out-of-date because it lives with the code, and compiler-integrated tooling like SourceKit can use it for documentation popouts in any editor. Tools like the refactoring engine are also aware of it (e.g. if you rename a parameter in Xcode using CMD+SHIFT+E, it will also rename the parameter in the documentation).
We can also use this tooling to generate documentation. The link above has one example. There are also loose plans to create a swift doc compiler mode which would use these to generate something like a unix manpage (discussion)
KarthikRIyer
@karwa I am not able to recall what you'd said about updating the docs. From what I can recall, you'd suggested to remove it from the README and instead use some specific kind of comments in the code. What would be the advantage apart from the README getting cleaner? Could you please describe it briefly? Sorry I'm unable to recall where we had that conversation. 😅