Generate API doc

[beltex]

Generate an API doc (like javadoc).

Swift support for this is coming. See:

• appledoc
  • Add support for Swift tomaz/appledoc#460 - will support in version 3.0
• jazzy
  • Support Xcode 6 GM realm/jazzy#34 - currently broken as of Xcode 6 - Beta 7

[beltex]

jazzy's had some major updates, so this can be looked at again.

[beltex]

Completed. Damn rpath held this up! :) Didn't realize that sourcekitten was looking for sourcekitd.framework under /Applications/Xcode.app/. Since I have multiple Xcode versions, there each under /Applications/<XCODE_VERSION>/Xcode.app/... to prevent conflicts. Made a symlink as a work around.

API doc can be seen here on the GitHub pages branch. It has issues (showing private entities, will file bug) as jazzy is still early in development, but it's nice nonetheless! :) Can add a copy to master branch in the future.

[beltex]

For reference

• Regarding private entities showing up in docs - Add command-line option to set the minimum access control to document realm/jazzy#69
• Coverage % - Display documentation coverage realm/jazzy#63 (comment)

[beltex]

Both issues addressed as of jazzy v0.0.17. Updated doc pushed.

[beltex]

Next is tuple returns, they don't render correctly. Not sure if this is because there being documented incorrectly in source, or if it's something on jazzy's end. Xcode seems to handle them fine.

[beltex]

How should a tuple return be documented? Normally it’s a single :returns: line, but since we have tuple returns now in Swift, should multiple :returns: lines be used? I couldn’t find an example in the Swift standard library (tuple return with any :returns: line). This is how jazzy currently handles it - example. Xcode handles it fine, but I’m not sure this is “correct” usage. Example code and Xcode render on option click below.

/**
...

:returns: valid True if the key is found, false otherwise
:returns: IOReturn IOKit return code
:returns: kSMC SMC return code
*/
public func isKeyValid(key: String) -> (valid: Bool, IOReturn: kern_return_t, kSMC: UInt8) {
...

[beltex]

For ref

• SourceKit editor.open request doesn't return global declarations or enum cases realm/jazzy#135
• Code not using Menlo font outside of README realm/jazzy#137

[beltex]

Also, for reference, could use this as well in the future - https://github.com/SwiftDocOrg/swiftdoc-parser