Naming conventions for structs and constructors

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.

mutable struct InitialState

     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

function simulate(initial::InitialState)

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

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.

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

What about:

For example, this works just fine:

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.

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

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:

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.