3 ms·

this article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their devel

by throw14082020 5y ago

this article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their developers) face. It has interesting examples. I think it will make documentation better, not because DocC is the perfect solution, but because it re-emphasises the importance of documentation because its new. It also gives developers at Apple a standard tool, was there such a thing before?.

duped 5y ago
You could run Doxygen on the header files in /Library/Developer and it would give you something decent that didn't strip the doc comments.
codys 5y ago
The general apple documentation for functions, etc appears to be pretty much a customized doxygen. One can see this by reading the header files for some of their frameworks and noting the doxygen comments there match up with their web-published documentation exactly. That said: some folks didn't really get the memo, because there are important details that are sometimes included in non-doxygen comments in Apple's headers and thus aren't reproduced into Apple's generated/published docs. In particular, the headers (sometimes) include annotations for specific types included in CF containers for return values.
JimDabell 5y ago
> It also gives developers at Apple a standard tool, was there such a thing before?. Yes, Jazzy, SwiftDoc, and appledoc already do this, plus whatever in-house tool that already existed at Apple before this (they have clearly been using something like this for the past ~15 years).
- throw14082020 5y ago
  Aren't all the ones you mentioned all third party, so I would expect they won't be used at all internally. That makes me wonder if Apple uses open source much internally. Also, DocC is integrated into Xcode, all the others tools could not be.

3 ms·

this article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their devel

by throw14082020 5y ago

duped 5y ago
You could run Doxygen on the header files in /Library/Developer and it would give you something decent that didn't strip the doc comments.
codys 5y ago
The general apple documentation for functions, etc appears to be pretty much a customized doxygen. One can see this by reading the header files for some of their frameworks and noting the doxygen comments there match up with their web-published documentation exactly. That said: some folks didn't really get the memo, because there are important details that are sometimes included in non-doxygen comments in Apple's headers and thus aren't reproduced into Apple's generated/published docs. In particular, the headers (sometimes) include annotations for specific types included in CF containers for return values.
JimDabell 5y ago
> It also gives developers at Apple a standard tool, was there such a thing before?. Yes, Jazzy, SwiftDoc, and appledoc already do this, plus whatever in-house tool that already existed at Apple before this (they have clearly been using something like this for the past ~15 years).
- throw14082020 5y ago
  Aren't all the ones you mentioned all third party, so I would expect they won't be used at all internally. That makes me wonder if Apple uses open source much internally. Also, DocC is integrated into Xcode, all the others tools could not be.