Internal documentation

Development Swift-DocC
11

Hi :wave:

About documenting internal APIs and implementation with Swift-DocC, I believe it is not only about which access level to include when generating the documentation. Let me explain.

Current state of the art: DocC is mainly focused in documenting public swift code, so libraries authors can add documentation for consumers:

  • This resulted in current implementation, where the markdown syntax has been enhanced with the goal of being able to reference to symbols or other documentation articles in the catalog
  • Furthermore, using relative paths for those references ([see the readme](subdirectory/README.md) VS <doc:README>) is not a good idea because this kind of documentation is usually exported and hosted somewhere separated from the code (usually a website): in such scenario there is no access to the code or the documentation source of truth
  • As a result, jumping from the documentation (in the xcode documentation navigator) to the actual source code seems to be not supported at the moment, and also not much needed: consumers are not interested on internal implementation details but rather just the public API
  • The validation of the references used in documentation articles is limited: DocC checks that the references exists (that the linked symbol or article exists). This simple check is usually enough to validate that documentation is up to date with public API

When documenting internal API or code, I believe the goals change. Hosting the documentation away from the code is not desired. Instead, likely the documentation would always stay as part of the repository, next to the code, and will serve as documentation to share between the authors of the package/packages (not the consumers):

  • Jumping from an article to code becomes more relevant, as the developer reading the documentation is likely interested in the internal implementation details and files being discussed in the documentation article (including the file locations in the repository)
  • In this case not only swift code will need to be documented, but likely non-swift code needs also to be referenced from the documentation. For example, the .swiftlint.yml file may be referenced in the documentation in case the documentation wants to include a mention to the swiftlint setup of the package
  • Due to above, referencing specific lines in local files (that are not swift symbols or other documentation articles) may be relevant. Currently a link like [this](path/to/local/file.txt) opens the url https://developer.apple.com/documentation/path/to/local/file when clicked, instead of opening the local file relative to the documentation article path
  • If part of a monorepo, the documentation may need to include references to other packages in the repository (while those packages are not dependencies), or to arbitrary files. And validation of these references is also not trivial
  • Maybe think one way to think about it is: how would DocC benefit the markdown articles created for swift evolution in swift-evolution/proposals at main · apple/swift-evolution · GitHub?
1 Like