How to document this

[roble]

I would like to add the documentation of a function to the official documentation page. It should have been a one liner to do this, but now I am somehow stuck…

There is already a docstring available. However, I need to add the function declaration to the docs/src/index.md file.

The function looks like this:

(I::UniformScaling)(n::Integer) = Diagonal(fill(I.λ, n))

And this is how I tried to add this to the index.md file:

(::LinearAlgebra.UniformScaling)(::Integer)

The doctests return the following error:

���   exception = `binding` cannot understand expression `::LinearAlgebra.UniformScaling`.
��� @ Documenter.Expanders /buildworker/worker/doctest_linux64/build/doc/deps/packages/Documenter/QQWIJ/src/Expanders.jl:285
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
ERROR: LoadError: `makedocs` encountered an error. Terminating build
Stacktrace:
 [1] error(::String) at ./error.jl:33
 [2] runner(::Type{Documenter.Builder.RenderDocument}, ::Documenter.Documents.Document) at /buildworker/worker/doctest_linux64/build/doc/deps/packages/Documenter/QQWIJ/src/Builder.jl:242
 [3] dispatch(::Type{Documenter.Builder.DocumentPipeline}, ::Documenter.Documents.Document) at /buildworker/worker/doctest_linux64/build/doc/deps/packages/Documenter/QQWIJ/src/Utilities/Selectors.jl:167
 [4] #2 at /buildworker/worker/doctest_linux64/build/doc/deps/packages/Documenter/QQWIJ/src/Documenter.jl:237 [inlined]
 [5] cd(::Documenter.var"#2#3"{Documenter.Documents.Document}, ::String) at ./file.jl:104
 [6] #makedocs#1 at /buildworker/worker/doctest_linux64/build/doc/deps/packages/Documenter/QQWIJ/src/Documenter.jl:236 [inlined]
 [7] top-level scope at /buildworker/worker/doctest_linux64/build/doc/make.jl:183
 [8] include(::Function, ::Module, ::String) at ./Base.jl:382
 [9] include(::Module, ::String) at ./Base.jl:370
 [10] exec_options(::Base.JLOptions) at ./client.jl:296
 [11] _start() at ./client.jl:506
in expression starting at /buildworker/worker/doctest_linux64/build/doc/make.jl:183
make: *** [html] Error 1
make: Leaving directory `/buildworker/worker/doctest_linux64/build/doc'
program finished with exit code 2
elapsedTime=308.675113

I already tried to replicate this error in REPL but it should have worked:

using LinearAlgebra, Documenter
@doc (::UniformScaling)(::Integer)  #returns the correct documentation

using Documenter
import LinearAlgebra
@doc (::LinearAlgebra.UniformScaling)(::Integer) #returns the correct documentation

I believe the issue is because Documenter misunderstands function like objects.

Does anyone know how to add these to the documentation page?
(Edit: ) This is linked to this pull request.

[zekeriya.sari]

I do not know why but using

```@autodocs
Modules = [MyPackage]

where MyPackage is the the module in which (::LinearAlgebra.UniformScaling)(::Integer) is throws no error.

Here is the case. The content of the module is

module MyPackage

using LinearAlgebra

"""
    (I::UniformScaling)(n::Integer)

Some explanation.
"""
(I::UniformScaling)(n::Integer) = Diagonal(fill(I.λ, n))

end # module

and the content of index.md is

# MyPackage.jl

```@autodocs

Modules = [MyPackage]

The resulting output is

[roble]

Thank you very much. I appreciate your detailed answer.

In your case, you used an @autodos block. Unfortunately, I cannot do this because I just need to extend an @docs block with the needed function declaration.

Nevertheless, I conclude from your tests that function like objects should not be an issue. This already helps

I already tried to find similar functions to see how they were documented. However, I could not find any… Would you know one?

[zekeriya.sari]

I browsed some well-documented packages, but could not find an example either. Then I tried the following.

If @docs is to be used, then specifying just the struct name suffices.

The content of the module file is

module MyPackage


struct MyType end

"""
    (I::MyType)(n::Integer)

Some explanation.
"""
(I::MyType)(n::Integer) = n + 1

export MyType

end # module

The content of index.md is

# MyPackage.jl

```@docs
MyType

and the result is

[zekeriya.sari]

But, if MyType is also documented, then just the first docstring is printed.

The module file:

module MyPackage


"""
    MyType 

Some type documentation. 
"""
struct MyType end

"""
    (I::MyType)(n::Integer)

Some explanation.
"""
(I::MyType)(n::Integer) = n + 1

export MyType

end # module

The index.md file,

# MyPackage.jl

```@docs
MyType

and the result is

[mortenpi]

You can do

```@docs
MyType
MyType(::Integer)
```

if you have a docstring for both the type and the functor.

But do note that you can run into trouble if you have a constructor and a functor method with the same signature – due to a docsystem bug, one of them will get overwritten by the other.

[roble]

I am thankful for you two @zekeriya.sari and @mortenpi looking into this. I think the PR where I had this issue passed the checks now and should sometime be merged