Swift-ify Documentation

[jpsphaxer]

Mostly covers TurboNavigator Documentation, with the exception of a couple files.

Made some small changes to the project's documentation with hopes to align more with Swift's DocC. Although most are esthetic changes .
You may preview these changes in XCode by Option + Click on element with doc comments.

cc: @joemasilotti - From previous PR on TurboNavigator repo

[joemasilotti]

Thanks for migrating your PR, @jpsphaxer! This is awesome, I love how nice it looks in Xcode now.

One question, though. It looks like all of the protocol functions in TurboNavigatorDelegate are marked as Required and have a note stating they are optional. Is that expected?

[jpsphaxer]

e all of the protocol functions

Hey @joemasilotti, I was thinking that overriding these functions was optional since a default implementation is provided. The idea was to replace the first line in the doc comments saying something like

/// Optional. Accept or reject a visit proposal 
/// ... 

For a note saying so instead

Would you prefer that we leave this doc comment as originally intended?

[joemasilotti]

You're correct, the functions are indeed optional because of the default implementations. I'm confused as to why the generated Xcode documentation says they are both required and optional.

[jpsphaxer]

You're correct, the functions are indeed optional because of the default implementations. I'm confused as to why the generated Xcode documentation says they are both required and optional.

OHH i see, let me do some digging into this. Great catch btw, I didn't see it.

[jpsphaxer]

@joemasilotti so the TL:DR - protocols are contracts and methods inside them are required by default. Even if we give a default implementation.

We could change the protocol to follow objc conventions and add @optional but that could limit the protocol's functionality and would require everything inside the protocol to be objc conformant.

I instead have pushed a change and propose we give a general doc note at the top level of the TurboNavigatorDelegate protocol explaining the optional implementation of the methods instead of each method's doc individually.

[joemasilotti]

Thanks for this! Merging in now.