If no group was specified, but a group by the same name as the user
exists, an error was raised in the situation where USERGROUPS_ENAB is
enabled in /etc/login.defs (which is the case for almost every major
linux distro). In this case, the user will be put in group 100 (which
is usually the "users" group on those same distros). This is currently
only done in the base class, as the issue may not exist on other
platforms like AIX or the BSDs.

Fixes #6210

(e.g. 'groups=' in the user module).

Revert "No longer need to reference 'version_added' in docs for these, as this was quite a while ago."

This reverts commit ff0a41d4.

Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

  Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

this works well for 'initial password setting' on user creation and avoids
having extra tasks and conditionals.
Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

Add support for Open and NetBSD platforms for user and group modules, including a new login_class parameter for FreeBSD, OpenBSD and NetBSD.

Also consolidated duplicate groups code into one get_groups_set() method.
Removed unused call to user_group_membership.
Removed sorting operations on set functions cause sets are inherently unordered.
Minor style improvements to match the rest of the code.

The new function will make the order of group names passed to the system command less determistic.
Which was already the case for modify_user_usermod() but not for other methods.
It will also strip out duplicate group names automatically which was not always the case previously.

Return public SSH key if the user module is called with generate_ssh_key=yes.
Since "user" doesn't overwrite files, this also allows querying of existing
public keys.

Used in playbooks together with the "register" keyword, the returned key can be
passed to the "authorized_key" module allowing easy setup of SSH public key
authentication between remote hosts.

modifications needed.
Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

Add nonunique option to user module, translating to the -o/--non-unique option to useradd and usermod.

Both modules seboolean and zfs have not been adapted since they defer from the default (either by having a 'null' or special state, or prefering "on"/"off" for state indication.