Merge pull request #54 from adrhill/ah/docs

Improve backend type docstrings
SciML · May 10, 2024 · d749b5a · d749b5a
2 parents cb4eb36 + 9b98c86
commit d749b5a
Showing 1 changed file with 53 additions and 81 deletions.
diff --git a/src/dense.jl b/src/dense.jl
@@ -1,15 +1,13 @@
 """
- AutoChainRules{RC}
-
-Chooses any AD library based on [ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl) (see the list [here](https://juliadiff.org/ChainRulesCore.jl/stable/index.html#ChainRules-roll-out-status)).
+ AutoChainRules(; ruleconfig)
 
-# Fields
+Struct used to select an automatic differentiation backend based on [ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl) (see the list [here](https://juliadiff.org/ChainRulesCore.jl/stable/index.html#ChainRules-roll-out-status)).
 
-- `ruleconfig::RC`: a [`ChainRulesCore.RuleConfig`](https://juliadiff.org/ChainRulesCore.jl/stable/rule_author/superpowers/ruleconfig.html) object.
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 
-# Constructor
+# Keyword Arguments
 
- AutoChainRules(; ruleconfig)
+- `ruleconfig::RC`: a [`ChainRulesCore.RuleConfig`](https://juliadiff.org/ChainRulesCore.jl/stable/rule_author/superpowers/ruleconfig.html) object.
 """
 Base.@kwdef struct AutoChainRules{RC} <: AbstractADType
  ruleconfig::RC
@@ -18,32 +16,28 @@ end
 mode(::AutoChainRules) = ForwardOrReverseMode() # specialized in the extension
 
 """
- AutoDiffractor
-
-Chooses [Diffractor.jl](https://github.com/JuliaDiff/Diffractor.jl).
+ AutoDiffractor()
 
-# Constructor
+Struct used to select the [Diffractor.jl](https://github.com/JuliaDiff/Diffractor.jl) backend for automatic differentiation.
 
- AutoDiffractor()
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 """
 struct AutoDiffractor <: AbstractADType end
 
 mode(::AutoDiffractor) = ForwardOrReverseMode()
 
 """
- AutoEnzyme{M}
+ AutoEnzyme(; mode=nothing)
+
+Struct used to select the [Enzyme.jl](https://github.com/EnzymeAD/Enzyme.jl) backend for automatic differentiation.
 
-Chooses [Enzyme.jl](https://github.com/EnzymeAD/Enzyme.jl).
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 
-# Fields
+# Keyword Arguments
 
 - `mode::M`: can be either 
  - an object subtyping `EnzymeCore.Mode` (like `EnzymeCore.Forward` or `EnzymeCore.Reverse`) if a specific mode is required
  - `nothing` to choose the best mode automatically
-
-# Constructors
-
- AutoEnzyme(; mode=nothing)
 """
 Base.@kwdef struct AutoEnzyme{M} <: AbstractADType
  mode::M = nothing
@@ -52,32 +46,28 @@ end
 mode(::AutoEnzyme) = ForwardOrReverseMode() # specialized in the extension
 
 """
- AutoFastDifferentiation
-
-Chooses [FastDifferentiation.jl](https://github.com/brianguenter/FastDifferentiation.jl).
+ AutoFastDifferentiation()
 
-# Constructor
+Struct used to select the [FastDifferentiation.jl](https://github.com/brianguenter/FastDifferentiation.jl) backend for automatic differentiation.
 
- AutoFastDifferentiation()
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 """
 struct AutoFastDifferentiation <: AbstractADType end
 
 mode(::AutoFastDifferentiation) = SymbolicMode()
 
 """
- AutoFiniteDiff{T1,T2,T3}
+ AutoFiniteDiff(; fdtype=Val(:forward), fdjtype=fdtype, fdhtype=Val(:hcentral))
 
-Chooses [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl).
+Struct used to select the [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) backend for automatic differentiation.
 
-# Fields
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
+
+# Keyword Arguments
 
 - `fdtype::T1`: finite difference type
 - `fdjtype::T2`: finite difference type for the Jacobian
 - `fdhtype::T3`: finite difference type for the Hessian
-
-# Constructor
-
- AutoFiniteDiff(; fdtype=Val(:forward), fdjtype=fdtype, fdhtype=Val(:hcentral))
 """
 Base.@kwdef struct AutoFiniteDiff{T1, T2, T3} <: AbstractADType
  fdtype::T1 = Val(:forward)
@@ -88,17 +78,15 @@ end
 mode(::AutoFiniteDiff) = ForwardMode()
 
 """
- AutoFiniteDifferences{T}
-
-Chooses [FiniteDifferences.jl](https://github.com/JuliaDiff/FiniteDifferences.jl).
+ AutoFiniteDifferences(; fdm)
 
-# Fields
+Struct used to select the [FiniteDifferences.jl](https://github.com/JuliaDiff/FiniteDifferences.jl) backend for automatic differentiation.
 
-- `fdm::T`: a [`FiniteDifferenceMethod`](https://juliadiff.org/FiniteDifferences.jl/stable/pages/api/#FiniteDifferences.FiniteDifferenceMethod)
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 
-# Constructor
+# Keyword Arguments
 
- AutoFiniteDifferences(; fdm)
+- `fdm::T`: a [`FiniteDifferenceMethod`](https://juliadiff.org/FiniteDifferences.jl/stable/pages/api/#FiniteDifferences.FiniteDifferenceMethod)
 """
 Base.@kwdef struct AutoFiniteDifferences{T} <: AbstractADType
  fdm::T
@@ -107,21 +95,16 @@ end
 mode(::AutoFiniteDifferences) = ForwardMode()
 
 """
- AutoForwardDiff{chunksize,T}
-
-Chooses [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl).
+ AutoForwardDiff(; chunksize=nothing, tag=nothing)
 
-# Type parameters
+Struct used to select the [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) backend for automatic differentiation.
 
-- `chunksize`: the preferred [chunk size](https://juliadiff.org/ForwardDiff.jl/stable/user/advanced/#Configuring-Chunk-Size) to evaluate several derivatives at once
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 
-# Fields
+# Keyword Arguments
 
+- `chunksize`: the preferred [chunk size](https://juliadiff.org/ForwardDiff.jl/stable/user/advanced/#Configuring-Chunk-Size) to evaluate several derivatives at once
 - `tag::T`: a [custom tag](https://juliadiff.org/ForwardDiff.jl/release-0.10/user/advanced.html#Custom-tags-and-tag-checking-1) to handle nested differentiation calls (usually not necessary)
-
-# Constructors
-
- AutoForwardDiff(; chunksize=nothing, tag=nothing)
 """
 struct AutoForwardDiff{chunksize, T} <: AbstractADType
  tag::T
@@ -134,21 +117,16 @@ end
 mode(::AutoForwardDiff) = ForwardMode()
 
 """
- AutoPolyesterForwardDiff{chunksize,T}
-
-Chooses [PolyesterForwardDiff.jl](https://github.com/JuliaDiff/PolyesterForwardDiff.jl).
+ AutoPolyesterForwardDiff(; chunksize=nothing, tag=nothing)
 
-# Type parameters
+Struct used to select the [PolyesterForwardDiff.jl](https://github.com/JuliaDiff/PolyesterForwardDiff.jl) backend for automatic differentiation.
 
-- `chunksize`: the preferred [chunk size](https://juliadiff.org/ForwardDiff.jl/stable/user/advanced/#Configuring-Chunk-Size) to evaluate several derivatives at once
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 
-# Fields
+# Keyword Arguments
 
+- `chunksize`: the preferred [chunk size](https://juliadiff.org/ForwardDiff.jl/stable/user/advanced/#Configuring-Chunk-Size) to evaluate several derivatives at once
 - `tag::T`: a [custom tag](https://juliadiff.org/ForwardDiff.jl/release-0.10/user/advanced.html#Custom-tags-and-tag-checking-1) to handle nested differentiation calls (usually not necessary)
-
-# Constructors
-
- AutoPolyesterForwardDiff(; chunksize=nothing, tag=nothing)
 """
 struct AutoPolyesterForwardDiff{chunksize, T} <: AbstractADType
  tag::T
@@ -161,17 +139,15 @@ end
 mode(::AutoPolyesterForwardDiff) = ForwardMode()
 
 """
- AutoReverseDiff
-
-Chooses [ReverseDiff.jl](https://github.com/JuliaDiff/ReverseDiff.jl).
+ AutoReverseDiff(; compile=false)
 
-# Fields
+Struct used to select the [ReverseDiff.jl](https://github.com/JuliaDiff/ReverseDiff.jl) backend for automatic differentiation.
 
-- `compile::Bool`: whether to [compile the tape](https://juliadiff.org/ReverseDiff.jl/api/#ReverseDiff.compile) prior to differentiation
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 
-# Constructor
+# Keyword Arguments
 
- AutoReverseDiff(; compile=false)
+- `compile::Bool`: whether to [compile the tape](https://juliadiff.org/ReverseDiff.jl/api/#ReverseDiff.compile) prior to differentiation
 """
 Base.@kwdef struct AutoReverseDiff <: AbstractADType
  compile::Bool = false
@@ -180,26 +156,22 @@ end
 mode(::AutoReverseDiff) = ReverseMode()
 
 """
- AutoSymbolics
-
-Chooses [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl).
+ AutoSymbolics()
 
-# Constructor
+Struct used to select the [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) backend for automatic differentiation.
 
- AutoSymbolics()
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 """
 struct AutoSymbolics <: AbstractADType end
 
 mode(::AutoSymbolics) = SymbolicMode()
 
 """
- AutoTapir
-
-Chooses [Tapir.jl](https://github.com/withbayes/Tapir.jl).
+ AutoTapir()
 
-# Constructor
+Struct used to select the [Tapir.jl](https://github.com/withbayes/Tapir.jl) backend for automatic differentiation.
 
- AutoTapir()
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 """
 struct AutoTapir <: AbstractADType end
 
@@ -208,7 +180,9 @@ mode(::AutoTapir) = ReverseMode()
 """
  AutoTracker
 
-Chooses [Tracker.jl](https://github.com/FluxML/Tracker.jl).
+Struct used to select the [Tracker.jl](https://github.com/FluxML/Tracker.jl) backend for automatic differentiation.
+
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 
 # Constructor
 
@@ -219,13 +193,11 @@ struct AutoTracker <: AbstractADType end
 mode(::AutoTracker) = ReverseMode()
 
 """
- AutoZygote
-
-Chooses [Zygote.jl](https://github.com/FluxML/Zygote.jl).
+ AutoZygote()
 
-# Constructor
+Struct used to select the [Zygote.jl](https://github.com/FluxML/Zygote.jl) backend for automatic differentiation.
 
- AutoZygote()
+Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
 """
 struct AutoZygote <: AbstractADType end