Update header comments & documentation

[robertmryan]

I noticed that the inline documentation, which was tailored for appledoc, didn’t render well within Xcode. For example, the documentation for FMDatabaseQueue looked like:

With this PR, it is now rendered like so:

Bottom line, I’ve wrapped code blocks with @code/@endcode, replaced back ticks with @c tags, etc. I’ve also fixed some problems (e.g. a #pragma between the comment and the @interface was preventing documentation from showing up; a private method that shouldn’t have been exposed has been hidden; etc.).

In full disclosure, I didn’t do much review of the content of the documentation, but focused largely on the formatting only. Also, this was a fairly cursory cleanup and I’m sure it’s not perfect, but it’s much better, IMHO.

Assuming you’re good with these fixes, I’d suggest rebuilding the gh-pages documentation, but rather than using appledoc (which doesn’t appear to have been updated in a very long time), I’ve found jazzy to be a little more up to date with modern auto-documenting conventions. I’ll do separate PR for that (if and when you approve this PR).

[ccgus]

Thanks for doing this! And of course, I merged the patches out of order I think? (That's just the way I roll)

[robertmryan]

@ccgus - No problem. I’m willing to stick a fork in 2.7.7. Do you mind if I tag it as a release (for Carthage users) and push the trunk to Cocoapods (assuming I even have that permission)? Or is there anything else you want to include in 2.7.7 before we do that?

[ccgus]

Yep, go ahead and push it on up. There's nothing else I want to include right now.