Detailed documentation for --publish?

I see examples of --publish everywhere in the docker docs, but I cannot find any actual documentation of these options, and what each of them do. Is this documentation anywhere?

For example, on a github issue there was this example to limit 1 container per node without having to use mode=global, so if my replicas > nodes, I should never see 2 of them in the same node:

-p mode=host,published=13999,target=13999

What does published and target actually do? Do I need both? And I’m already using --network host, do I need to specify mode=host again here?



EXPOSE (incoming ports)
The following run command options work with container networking:

--expose=[]: Expose a port or a range of ports inside the container.
             These are additional to those exposed by the `EXPOSE` instruction
-P         : Publish all exposed ports to the host interfaces
-p=[]      : Publish a container᾿s port or a range of ports to the host
               format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort
               Both hostPort and containerPort can be specified as a
               range of ports. When specifying ranges for both, the
               number of container ports in the range must match the
               number of host ports in the range, for example:
                   -p 1234-1236:1234-1236/tcp

               When specifying a range for hostPort only, the
               containerPort must not be a range.  In this case the
               container port is published somewhere within the
               specified hostPort range. (e.g., `-p 1234-1236:1234/tcp`)

               (use 'docker port' to see the actual mapping)

that was a quick google search

docker run publish

That doesn’t explain anything of what was asked.
It doesn’t tell what are the options for -p, it doesn’t have any explanations for mode, published or target.

got it…

I have never seen that syntax either…
see docker service create , Publish service ports externally to the swarm (-p, –publish)

again this was a google search

docker publish mode