Naming conventions for structs and constructors

General Usage
1

I often have a struct and one or more constructors for the struct, e.g.

"""
    mutable struct InitialState

This struct stores the state of the model at the beginning of an iteration of the learning
algorithm. It is updated at the end of each iteration.

$(TYPEDFIELDS)
"""
mutable struct InitialState
    t0::Float64      
    t_sim::Float64
    u_est::Float64 
end

"""
     InitialState(; Γ = 1.0, Γest=1.0, Δα=0.0, Δα_est=0.0, offset=0.0)

Create an initial state for the given parameters.
"""
function InitialState(; Γ = 1.0, Γest=1.0, Δα=0.0, Δα_est=0.0, offset=0.0)
    init = InitialState(0,0,0)
    init.t0 = 0
    # T = 1/(se.w_ex/2pi)
    # init.t_sim =  round(se.t_iter_alpha/T) * T # about 10min
    ...
    init
end

function simulate(initial::InitialState)
    println(initial.t0)
end

While the code works fine, I get problems with vscode and with Documenter.

vscode complains if I use init::InitialState in a function signature. It thinks InitialState is a function and not a type (well, it is both).

With Documenter I get the same problem, it cannot distinguish between the type and the function
and if I document both it complains about a duplicate definition.

What is best practice? Always use different names for the type and the functions that construct the
type?

2

With your example above I can’t reproduce this, everything works as expected for me. Can you provide an MWE?

Can you provide an MWE? In the example above there is just one docstring, and no information on how you try to incorporate these into Documenters @docs block.

3

OK, I update the example above to have two docstrings…

4

What about:

For example, this works just fine:

```@docs
TestPackage.InitialState   # struct type docs
TestPackage.InitialState() # constructor docs
```

Your updated example doesn’t show any warnings like you mention:

It would be useful if you can provide examples that reproduce your problems.

5

Per point 8 of that link, maybe there’s a discrepancy in the environments influencing how this problem happens?

6

Sometimes I get strange behaviors from the linter. Not reproducible, or I’d open an issue. The only way I could fix it was to uninstall and reinstall the extension.:man_shrugging:

7

It works for me now. I put the struct definition and the constructor functions in the same file. This seams to help. Also thanks for the tip to refer to the function in Documenter as InitialState() and to the type as InitialState. This makes Documenter happy.

Conclusion: Different names are not required.