Clean up the API Consistency & Documentation

[danthorpe]

Before 3.0 I want to ensure that APIs have consistent naming, argument ordering etc. They should also be aligned with Swift API guidelines (but not written in Swift 3.0 yet) and existing Cocoa conventions.

[ghost]

I have one question related to that.

Is it planned at some point to add class prefixes?

I know it is technically not needed because Swift defines modules that act like namespaces, but it can help organize and identify the code better. It also would comply with the Cocoa conventions where everything inside a Framework starts with a common prefix, so every consumer immediately knows where it's came from.

[danthorpe]

Hi @blg-andreasbraun - will not be adding class prefixes.

When Swift PM is a little bit more mature, and it's clearer how to create cross platform frameworks with support for extension compatible API variants, which will more than likely result in sub-module definitions, my hope is that the code becomes a little bit more organised, and the module namespace less dense.