Documentation for states.state.module is incorrect

[vernondcole]

Description of Issue/Question

The documentation in https://docs.saltstack.com/en/develop/ref/states/all/salt.states.module.html#execution-of-salt-modules-from-within-states is incorrect, and contains no
actual description of the salt.states.module.run call.

The doc gives the example:

mine.send:
  module.run:
    - network.interfaces

Setup

Install a fresh salt master, today's develop HEAD, in a virtual machine.

Steps to Reproduce Issue

I create a similar state in bevy_master.sls:

update_the_grains:
  module.run:
    - saltutil.sync_grains

and the result is:

vagrant@bevymaster:~$ sudo salt-call state.apply bevy_master
local:
    Data failed to compile:
----------
    Too many functions declared in state 'module' in SLS 'bevy_master'

So I remove the "-"

update_the_grains:
  module.run:
    saltutil.sync_grains

This time I get:

vagrant@bevymaster:~$ sudo salt-call state.apply bevy_master
local:
    Data failed to compile:
----------
    State 'update_the_grains' in SLS 'bevy_master' is not formed as a list

Oh, well. Go back to the old way of saying it:

update_the_grains:
  module.run:
    - name: saltutil.sync_grains

and get:

vagrant@bevymaster:~$ sudo salt-call state.apply bevy_master
[WARNING ] The function "module.run" is using its deprecated version and will expire in version "Sodium".

There is no way to win.

Versions Report

At the bottom of the html page it says:

Generated on December 07, 2017 at 07:11:35 MST.
You are viewing docs built from a recent snapshot of the develop branch. `

vagrant@bevymaster:~$ salt --versions-report
Salt Version:
           Salt: 2017.7.0-892-g9865a31
 
Dependency Versions:
           cffi: 1.5.2
       cherrypy: Not Installed
       dateutil: Not Installed
      docker-py: Not Installed
          gitdb: Not Installed
      gitpython: Not Installed
          ioflo: Not Installed
         Jinja2: 2.8
        libgit2: 0.24.0
        libnacl: Not Installed
       M2Crypto: Not Installed
           Mako: Not Installed
   msgpack-pure: Not Installed
 msgpack-python: 0.4.6
   mysql-python: Not Installed
      pycparser: 2.14
       pycrypto: 2.6.1
   pycryptodome: Not Installed
         pygit2: 0.24.0
         Python: 2.7.12 (default, Nov 20 2017, 18:23:56)
   python-gnupg: Not Installed
         PyYAML: 3.11
          PyZMQ: 15.2.0
           RAET: Not Installed
          smmap: Not Installed
        timelib: Not Installed
        Tornado: 4.2.1
            ZMQ: 4.1.4
 
System Versions:
           dist: Ubuntu 16.04 xenial
         locale: UTF-8
        machine: x86_64
        release: 4.4.0-21-generic
         system: Linux
        version: Ubuntu 16.04 xenial

[vernondcole]

With no actual description of the calling parameters, there is no way of guessing what is wanted.

[lorengordon]

Not sure why the documented list form isn't working, but I think you were close with this one:

update_the_grains:
  module.run:
    saltutil.sync_grains

The doc (which is confusing in the presentation of new vs old forms) does have examples where the new form is a dictionary:

call_something:
  module.run:
    git.fetch:
      - cwd: /path/to/my/repo
      - user: myuser
      - opts: '--all'

So, based on that example, I think if you write yours as a dictionary, it will work without the deprecation warning:

update_the_grains:
  module.run:
    saltutil.sync_grains: {}

[marco-m]

Hello @Ch3LL I don't think this is blocked by an answer for @vernondcole , since what he reports is still valid, I can only copy and paste his text:

The very first example in the documentation

mine.send:
  module.run:
    - network.interfaces

is simply broken :-)

[Ch3LL]

does this work for you:

mine.send:
  module.run:
    - network.interfaces: []

[marco-m]

here is what I get:

$ sudo salt-call state.apply foo
[WARNING ] The function "module.run" is using its deprecated version and will expire in version "Sodium".
[ERROR   ] The following arguments are missing: func
local:
----------
          ID: mine.send
    Function: module.run
      Result: False
     Comment: The following arguments are missing: func
     Started: 19:58:49.376001
    Duration: 1.514 ms
     Changes:

Summary for local
------------
Succeeded: 0
Failed:    1

[Ch3LL]

apologies the way its written is with the new format, which requires in the config:

use_superseded:
  - module.run

I think we can definitely improve the documentation to clearly show which format is which.