Doc style

[oyamad]

See https://github.com/QuantEcon/Games.jl/pull/1#issuecomment-185396785.

• Follow Julia manual + QuantEcon/QuantEcon.jl#58 and QuantEcon.jl/Style Guide?
• Follow QuantEcon/QuantEcon.jl#136 to use Documenter.jl?

[shizejin]

Documenter.jl is actually using what JuliaLang suggests.

To adopt this style, change

"""
Constructor of an N-player NormalFormGame, consisting of payoffs all 0.

##### Arguments

- `T::Type` : Type of payoff values; defaults to `Float64` if not specified.
- `nums_actions::NTuple{N,Int}` : Numbers of actions of the N players.

"""
function NormalFormGame{N}(T::Type, nums_actions::NTuple{N,Int})
    # TODO: can we still get inference to work but avoid the `::NTuple` below?
    players::NTuple{N,Player{N,T}} =
        ntuple(i -> Player(zeros(tuple(nums_actions[i:end]...,
                                       nums_actions[1:i-1]...))),
               N)
    return NormalFormGame{N,T}(players, nums_actions)
end

to

"""
    NormalFormGame{N}(T::Type, nums_actions::NTuple{N,Int})

Constructor of an N-player NormalFormGame, consisting of payoffs all 0.

# Arguments
* `T::Type`: Type of payoff values; defaults to `Float64` if not specified.
* `nums_actions::NTuple{N,Int}`: Numbers of actions of the N players.
"""
function NormalFormGame{N}(T::Type, nums_actions::NTuple{N,Int})
    # TODO: can we still get inference to work but avoid the `::NTuple` below?
    players::NTuple{N,Player{N,T}} =
        ntuple(i -> Player(zeros(tuple(nums_actions[i:end]...,
                                       nums_actions[1:i-1]...))),
               N)
    return NormalFormGame{N,T}(players, nums_actions)
end

[sglyon]

That style looks good to me.

I would vote that we add a new line between the header # Arguments and the list.

Also, I prefer - to *, but since they are equivalent in markdown I'm happy either way

[oyamad]

+1 for adding a new line between the header # Arguments and the list.

[shizejin]

I agree. We don't need to follow the Julia suggested style strictly, as it won't make difference to the output of Documenter.jl, while make the raw docstrings much nicer.

[cc7768]

This all looks really good. Thanks @shizejin!

[shizejin]

Two modifications to the doc style (discussed with @oyamad and @QBatista):

1. Change * to - following Julia manual.
2. Remove the type declarations from the header.

"""
    NormalFormGame{N}(T, nums_actions)

Constructor of an N-player NormalFormGame, consisting of payoffs all 0.

# Arguments
- `T::Type`: Type of payoff values; defaults to `Float64` if not specified.
- `nums_actions::NTuple{N,Int}`: Numbers of actions of the N players.
"""
function NormalFormGame{N}(T::Type, nums_actions::NTuple{N,Int})
    # TODO: can we still get inference to work but avoid the `::NTuple` below?
    players::NTuple{N,Player{N,T}} =
        ntuple(i -> Player(zeros(tuple(nums_actions[i:end]...,
                                       nums_actions[1:i-1]...))),
               N)
    return NormalFormGame{N,T}(players, nums_actions)
end