Improve docs for structs: constructors and functors #366
Conversation
| For the functor, use `bar::Bar`, i.e. | ||
|
|
||
| ```julia | ||
| function ChainRulesCore.rrule(bar::Bar, x, y) |
There was a problem hiding this comment.
@oxinabox just double checking this is right?
There was a problem hiding this comment.
This is right.
Though I think that seperating constructors into a seperate section to Functors might be clearer.
and have the functor section say somehting like "In constrast to defined the rule for constructing an object, one can overload the rule for calling an instance of an object (if that object is a functor)"
or somehting like that.
Still even with them together this is a clear enhancement to the docs, so I am happy to have it merged and then to a follow up if you like
Codecov Report
@@ Coverage Diff @@
## master #366 +/- ##
=======================================
Coverage 87.23% 87.23%
=======================================
Files 13 13
Lines 478 478
=======================================
Hits 417 417
Misses 61 61 Continue to review full report at Codecov.
|
|
|
||
| Do not use `@not_implemented` if the differential does not exist mathematically (use `NoTangent()` instead). | ||
|
|
||
| ## Code Style |
There was a problem hiding this comment.
Moving code in the same PR as edits somehting else makes reviewing harder.
It's not terrible in this case since the PR is small, but still like 1/2 the changed lines are moving this)
docs/src/writing_good_rules.md
Outdated
| a::Float64 | ||
| end | ||
|
|
||
| (bar::Bar)(x, y) = return bar.a + x + y # functor |
There was a problem hiding this comment.
| (bar::Bar)(x, y) = return bar.a + x + y # functor | |
| (bar::Bar)(x, y) = return bar.a + x + y # functor (i.e. callable object, overloading the call action) |
|
Thanks for taking over this! I'll leave Lyndon to review. I think Seth also had some comments on the previous PR :) |
docs/src/writing_good_rules.md
Outdated
|
|
||
| ```julia | ||
| function ChainRulesCore.rrule(bar::Bar, x, y) | ||
| ... |
There was a problem hiding this comment.
including the code for the pullback i think is important.
Possibly also emphasize above that this is what that first arg is for.
| ... | |
| # Notice the first return is not `NoTangent()` | |
| Bar_pullback(z̄) = Tangent{Bar}(;a=z̄), z̄, z̄ |
| To define an `rrule` for a constructor for a _type_ `Bar` we need to be careful to dispatch only on `Type{Bar}`. | ||
| For example, the `rrule` signature for a `Bar` constructor would be like: | ||
| ```julia | ||
| function ChainRulesCore.rrule(::Type{Bar}, a) |
There was a problem hiding this comment.
I think Seth's point about <: (for non-concrete types) is worth making too
#331 (comment)
There was a problem hiding this comment.
in general probably should always use <: inside Type.
Since it means your code doesn't have to change if it gains type-parameters, and thus is no longer concrete.
Plus saves thinking
(possibly even this should be added to BlueStyle)
This builds off @nickrobinson251's https://github.com/JuliaDiff/ChainRulesCore.jl/pull/331/files and adds an example struct, as well as adds a note on functors. I've also moved the Code Style to the top, as the generic signature is the most common thing people want.
Closes #315