Fix docs & reorganize them some

[JulianGriggs]

Short description of what this PR does:

• Fixes some errors in the documentation (makes sure that the mentioned method is accurately reflected in the example)
• Adds some basic inline comments
• Moves code example above description for consistency
• Modifies some language (ex. "you are better of just using" => "it is recommended that you use")

Checklist

• [x] I have made a material change to the repo (functionality, testing, spelling, grammar)
• [x] I have read the [Contribution Guide] and my PR follows them.
• [x] I updated my branch with the master branch.
• [x] I have added tests that prove my fix is effective or that my feature works
• [x] I have added necessary documentation about the functionality in the appropriate .md file
• [x] I have added in line documentation to the code I modified

Closes #

[JulianGriggs]

@austinlparker Looks like you have rights to this repo so I'm mentioning you here. Curiously I don't have the ability to add you assign you as a reviewer through the GitHub UI...

[austinlparker]

huh, weird. I'll take a look at this later today. tks!