Thoughts on Swift's embedded Comment Documentation System
The Swift server packages are documented with the inline comment documentation system. I went ahead and used it for my recent test mule project (femtoblogger, you're soaking in it).
It's easy enough to add documentation, Xcode has a CMD-click Add Documentation menu that will jam in a template for your function with spaces for all the parameters and return types. You just type markdown after that. If you add an argument, click it again. Xcode will add more template.
Now people can Option-click on your function name (or whatever) and get a lovely Quick Help pop up.
I appreciate this greatly for libraries.
But…
There doesn't seem to be any pathway from this snippets to a real document where the big picture is explained, and all the functions listed in well organized categories. You know,… like the good old Apple documentation.
"Good enough" is the enemy of "Good".
This isn't a special flaw for the Swift comment based documentation. Essentially all in code systems I've ever used have suffered from this. (Halfway excepting one I wrote, but you can't use.)
The Moral
- Do your "in code" comments.
- Update your "in code" comments when you change the code.
- Write book like documentation somewhere! and put the links to it in HUGE type in the middle of your project page.