# Documenting abstract types & Documenter.jl

**URL:** <https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022>\
**Category:** General Usage\
**Tags:** question, documenter\
**Created:** [February 10, 2017, 11:25am UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022 "2017-02-10T11:25:30Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![stustd](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stustd/32/21430_2.png) [@stustd](https://discourse.julialang.org/u/stustd)\
**Post date:** [February 10, 2017, 11:25am UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/1 "2017-02-10T11:25:30Z")

</div>

I have problems documenting an abstract type hierarchy when subtyping multiple multiple abstract type. I’m using Documenter.jl’s native :html generation (i.e. don’t use mkdocs).

Example in case:

```julia
"Doc A"
abstract A
"Doc B"
abstract B <: A # no documentation problems so far

"Doc C"
abstract C
"Doc D"
abstract D <: A, C # Problem: "WARNING: replacing docs for C..."

```

The produced html shows the following anomalies:

1. Documentation of types subtyped from is being replaced by D’s documentation during julia _compilation_.
2. Only the first and not all types D is subtyping from are mention in D’s documentation.

Any ideas?

---

<div class="post-metadata">

**Author:** ![mauro3](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mauro3/32/292_2.png) [@mauro3](https://discourse.julialang.org/u/mauro3)\
**Post date:** [February 10, 2017, 12:39pm UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/2 "2017-02-10T12:39:43Z")

</div>

There is no multiple inheritance in Julia. Note that this:

```julia
julia> abstract D <: A, C
(nothing,C)

```

returns a tuple, i.e. it defines the type `D` which returns `nothing`, and puts that into a tuple with `C`. So, no subtyping with `C` happens. Now for some reason the docs get attached to `C`, thus the warning.

Arguably, `abstract D <: A, C`should be a syntax error (although that might not be possible).

---

<div class="post-metadata">

**Author:** ![stustd](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stustd/32/21430_2.png) [@stustd](https://discourse.julialang.org/u/stustd)\
**Post date:** [February 10, 2017, 2:20pm UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/3 "2017-02-10T14:20:29Z")

</div>

Hm…, coming from Python …

In a complex mixed-feature type hierarchy, what’s the right julia idom combining features in types? Only traits? But traits are based on abstract types so must every feature set (i.e. possible combination of features) then (overwhelmingly…) have its own abstract type…?

---

<div class="post-metadata">

**Author:** ![tbreloff](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tbreloff/32/68_2.png) [@tbreloff](https://discourse.julialang.org/u/tbreloff)\
**Post date:** [February 10, 2017, 2:42pm UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/4 "2017-02-10T14:42:36Z")

</div>

> [@stustd](#):
>
> In a complex mixed-feature type hierarchy, what’s the right julia idom combining features in types?

“You must unlearn what you have learned”

Stop worrying so much about types. The OOP mindset is horribly wasteful and inelegant. If you find yourself focused on problems like “well… a TA is both a `Student` **and** a `Teacher`… I probably need the diamond pattern”, _stop, just do_.

```julia
abstract Person
type TA <: Person end
type Professor <: Person end

teach(::TA) = ...
teach(::Professor) = ...

```

If your example is so big and complex that this doesn’t work well, then 1) consider if you’re making it more complex than it needs to be, or 2) use traits.

I’ve written a lot of Julia code (and way more C++/Python code), and this approach has yet to limit what I can do.

---

<div class="post-metadata">

**Author:** ![tbreloff](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tbreloff/32/68_2.png) [@tbreloff](https://discourse.julialang.org/u/tbreloff)\
**Post date:** [February 10, 2017, 3:56pm UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/5 "2017-02-10T15:56:17Z")

</div>

Another approach you might want to consider is to use parameters. Here’s an example:

```julia
julia> abstract BoolType

julia> type TRUE <: BoolType end

julia> type FALSE <: BoolType end

julia> abstract Person{TEACH<:BoolType, LEARN<:BoolType}

julia> type TA <: Person{TRUE,TRUE} end

julia> type Professor <: Person{TRUE,FALSE} end

julia> teach(x) = error("$x can't teach!")
teach (generic function with 1 method)

julia> teach(x::Person{TRUE}) = "what a great teacher!"
teach (generic function with 2 methods)

julia> teach(TA())
"what a great teacher!"

julia> teach(Professor())
"what a great teacher!"

julia> type Student <: Person{FALSE,TRUE} end

julia> teach(Student())
ERROR: Student() can't teach!
 in teach(::Student) at ./REPL[7]:1

```

---

<div class="post-metadata">

**Author:** ![stustd](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stustd/32/21430_2.png) [@stustd](https://discourse.julialang.org/u/stustd)\
**Post date:** [February 10, 2017, 10:13pm UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/6 "2017-02-10T22:13:41Z")

</div>

@mauro3 Yes indeed… Have started to reimplement the desing with your SimpleTraits (nice, thanks). Multitraits is not functional yet, is it?

---

<div class="post-metadata">

**Author:** ![stustd](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stustd/32/21430_2.png) [@stustd](https://discourse.julialang.org/u/stustd)\
**Post date:** [February 10, 2017, 10:52pm UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/7 "2017-02-10T22:52:16Z")

</div>

@tbreloff Yet with a growing number of abstract parameters (traits) we’re going to see an explosion of methods. Just add this:

```julia
learn(x) = error("$x can't learn!")

learn(x::Person{TRUE,TRUE}) = "what a great student!"
learn(x::Person{FALSE,TRUE}) = "what a great student!"

learn(Student())

```

where we need to address both TEACH-ing possibilities. (Not to think of having \>3 different boolean trait choices…).

@mauro3’s SimpleTrait/multitrait would solve this…

---

<div class="post-metadata">

**Author:** ![dpsanders](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dpsanders/32/3573_2.png) [@dpsanders](https://discourse.julialang.org/u/dpsanders)\
**Post date:** [February 10, 2017, 11:50pm UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/8 "2017-02-10T23:50:48Z")

</div>

```julia
julia> learn{T<:BoolType}(x::Person{T,TRUE}) = "what a great student!"
learn (generic function with 2 methods)

julia> learn(Student())
"what a great student!"

```

---

<div class="post-metadata">

**Author:** ![stustd](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stustd/32/21430_2.png) [@stustd](https://discourse.julialang.org/u/stustd)\
**Post date:** [February 11, 2017, 9:49pm UTC](https://discourse.julialang.org/t/documenting-abstract-types-documenter-jl/2022/9 "2017-02-11T21:49:07Z")

</div>

@dpsanders Thanks for showing how to capitalize on Julia’s builtin strength.

@tbreloff Thanks for showing the elegance of parameterized abstract types.