Generate API doc - Githubissues

beltex / SMCKit

Apple SMC library & tool

https://beltex.github.io/SMCKit

MIT License

473 stars 55 forks source link

Generate API doc #3

Closed beltex closed 9 years ago

beltex commented 10 years ago

Generate an API doc (like javadoc).

Swift support for this is coming. See:

appledoc
- https://github.com/tomaz/appledoc/issues/460 - will support in version 3.0
jazzy
- https://github.com/realm/jazzy/issues/34 - currently broken as of Xcode 6 - Beta 7

beltex commented 9 years ago

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

beltex commented 9 years ago

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 commented 9 years ago

For reference

Regarding private entities showing up in docs - https://github.com/realm/jazzy/issues/69
Coverage % - https://github.com/realm/jazzy/issues/63#issuecomment-66935210

beltex commented 9 years ago

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

beltex commented 9 years ago

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 commented 9 years ago

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) {
...

xcode-comment

beltex commented 9 years ago

For ref

beltex commented 9 years ago

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