# How to document this

**URL:** <https://discourse.julialang.org/t/how-to-document-this/39217>\
**Category:** General Usage\
**Tags:** documentation, documenter, linearalgebra\
**Created:** [May 10, 2020, 8:59am UTC](https://discourse.julialang.org/t/how-to-document-this/39217 "2020-05-10T08:59:48Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![roble](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/roble/32/12303_2.png) [@roble](https://discourse.julialang.org/u/roble)\
**Post date:** [May 10, 2020, 8:59am UTC](https://discourse.julialang.org/t/how-to-document-this/39217/1 "2020-05-10T08:59:48Z")

</div>

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](https://github.com/JuliaLang/julia/blob/381693d3dfc9b7072707f6d544f82f6637fc5e7c/stdlib/LinearAlgebra/src/uniformscaling.jl#L74) looks like this:

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

```

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

```julia
(::LinearAlgebra.UniformScaling)(::Integer)

```

The doctests return the following error:

```julia
��� 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:

```julia
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](https://docs.julialang.org/en/v1/manual/methods/#Function-like-objects-1).

Does anyone know how to add these to the documentation page?  
(Edit: ) This is linked to this [pull request](https://github.com/JuliaLang/julia/pull/35705).

---

<div class="post-metadata">

**Author:** ![zekeriya.sari](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/zekeriya.sari/32/13695_2.png) [@zekeriya.sari](https://discourse.julialang.org/u/zekeriya.sari)\
**Post date:** [May 10, 2020, 11:41am UTC](https://discourse.julialang.org/t/how-to-document-this/39217/2 "2020-05-10T11:41:01Z")

</div>

I do not know why but using

````julia
```@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

```julia
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

````julia
# MyPackage.jl

```@autodocs

Modules = [MyPackage]

````

The resulting output is

 ![documenter_output](https://global.discourse-cdn.com/julialang/original/3X/f/b/fbe4033e342d2de4d6305f26ddf5064f70666581.png)

---

<div class="post-metadata">

**Author:** ![roble](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/roble/32/12303_2.png) [@roble](https://discourse.julialang.org/u/roble)\
**Post date:** [May 10, 2020, 4:10pm UTC](https://discourse.julialang.org/t/how-to-document-this/39217/3 "2020-05-10T16:10:17Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![zekeriya.sari](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/zekeriya.sari/32/13695_2.png) [@zekeriya.sari](https://discourse.julialang.org/u/zekeriya.sari)\
**Post date:** [May 10, 2020, 7:28pm UTC](https://discourse.julialang.org/t/how-to-document-this/39217/4 "2020-05-10T19:28:32Z")

</div>

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

```julia
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

````julia
# MyPackage.jl

```@docs
MyType

````

and the result is

 ![documenter_output_2](https://global.discourse-cdn.com/julialang/original/3X/2/b/2b0c2ea5e4deef9059e7c8ec8a7e29f5098eb434.png)

---

<div class="post-metadata">

**Author:** ![zekeriya.sari](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/zekeriya.sari/32/13695_2.png) [@zekeriya.sari](https://discourse.julialang.org/u/zekeriya.sari)\
**Post date:** [May 10, 2020, 7:39pm UTC](https://discourse.julialang.org/t/how-to-document-this/39217/5 "2020-05-10T19:39:57Z")

</div>

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

The module file:

```julia
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,

````julia
# MyPackage.jl

```@docs
MyType

````

and the result is

 ![documenter_output_3](https://global.discourse-cdn.com/julialang/original/3X/3/a/3a29522ec24175e47f6399e667bd6f6470dce560.png)

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [May 11, 2020, 12:51am UTC](https://discourse.julialang.org/t/how-to-document-this/39217/6 "2020-05-11T00:51:33Z")

</div>

You can do

````julia
```@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.

---

<div class="post-metadata">

**Author:** ![roble](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/roble/32/12303_2.png) [@roble](https://discourse.julialang.org/u/roble)\
**Post date:** [June 22, 2020, 9:57am UTC](https://discourse.julialang.org/t/how-to-document-this/39217/7 "2020-06-22T09:57:58Z")

</div>

I am thankful for you two @zekeriya.sari and @mortenpi looking into this. I think the [PR where I had this issue](https://github.com/JuliaLang/julia/pull/35705) passed the checks now and should sometime be merged