Understanding recipes in Plots.jl

[ChrisRackauckas]

@juliohm

I will try add the plt::Plot argument to the argument list and see what happens, even though I don’t understand what is happening under the hood.

Oh, this is just a standard Julia design. Instead of writing two different implementations when you have a mutating function, you just make the non-mutating version pass to the mutating version.

f!(y,x) # does something mutating to x
function f(x) 
  y = similar(x)
  f!(y,x)
  y
end

This is a very common structure in Julia because mutating allows things to be faster, and sometimes allows more functionality. So for plot recipes, the implementation is really just plot!(dispatch_type,plot, args...) which adds a new dispatch_type recipe to an existing plot. This style of using dispatch on types to add extend functionality to a common function call is described here:

Modular Algorithms for Scientific Computing in Julia - Stochastic Lifestyle

So then the out-of-place plot silently adds in the current plot and calls plot! and continues. So what you’re really defining is a new plot! function with a new type, where the first argument is a type which controls its dispatch. Make sense?

@juliohm

In terms of documentation, I feel it was written by the authors to the co-authors. As someone coming from outside, a normal user, I can’t catch up easily, which is paradoxical since one of the goals of Plots.jl is to “just work” out of the box with no need to memorize syntax nor function prototypes. I think a lot of the attention in the docs has been put into the internal machinery and less on the available customization options, makes sense?

But this page describes all of the customization options, does it not?

https://juliaplots.github.io/attributes/

But I think what you’re looking for is more of an “Introduction to Plots”. I think a package manual should go through all of the details and explain everything it can do, which is what the docs currently do. A separate thing would be a quicker “Dive Into Plots”, and someone should write something like that.

@juliohm

Anyways, I wish I could understand the API more to document it myself, but this is a chicken or egg problem: I don’t understand enough to document, there is no documentation to understand.

The easiest way is to ask a question, and once it makes sense, make a PR for the docs.