[salt] add a state to make sure the system is uptodate
[salt] clean up and document

clean up for pep8 and document uptodate
Be more explicit in the pacman module

If we are going to be more explicit, we should be more explicit
throughout the entire thing.  From issue 10519.
Minor tweaks to new pkg.uptodate state

2 minor changes:

1. Moved state function up above mod_init(). This is just for
   consistency across the codebase, mod_init() typically just appears at
   the bottom of the .py file (and if it's not there it probably should
   be).

2. Used a versionadded RST directive to note that this state is not yet
   available, as our automated docs builds will otherwise make it seem
   like this state is available for immediate use once your pull request
   is merged upstream.
Merge pull request #10712 from gtmanfred/uptodate

Uptodate