[julia-users] Is there a natural way to use the same docstring for multiple functions?
Hi everyone, quick question about docstrings. Sometimes it makes sense to use the same help text for different functions; I'm particularly thinking mutating and non-mutating versions of the same algorithm. Is there a natural way to reuse a docstring for different functions (either in Docile.jl or in v0.4 base)? Specifically, I'm doing something like the following, but would prefer to avoid the temporary variable `recursive_ols_doc` if possible (for style reasons, if nothing else), and without writing the documentation in a separate file. recursive_ols_doc = Calculates the OLS estimators for the model y ~ x recursively... * `recursive_ols` is a wrapper that works like this... * `recursive_ols!` does all the real work like that... @doc recursive_ols_doc - function recursive_ols!(estimates::Array, y, x) ## Calculations end @doc recursive_ols_doc - function recursive_ols(y, x, R::Integer) ## preallocate, then call recursive_ols! end Thanks! (Really liking this documentation tool, btw)
Re: [julia-users] Is there a natural way to use the same docstring for multiple functions?
Oh, perfect. The @doc (@doc ) construction is exactly what I was looking for. Thanks! On Tuesday, January 13, 2015 at 2:35:09 PM UTC-6, Mike Innes wrote: That should pretty much work as is, but you'll want to use the `doc` string macro for markdown formatting, i.e. recursive_ols_doc = doc The other thing you can do is document one function, then retrieve that functions docs with the @doc macro: @doc foo - function recursive_ols() ... @doc (@doc recursive_ols) - function recursive_ols!() ... On 13 January 2015 at 19:49, Gray Calhoun gcal...@iastate.edu javascript: wrote: Hi everyone, quick question about docstrings. Sometimes it makes sense to use the same help text for different functions; I'm particularly thinking mutating and non-mutating versions of the same algorithm. Is there a natural way to reuse a docstring for different functions (either in Docile.jl or in v0.4 base)? Specifically, I'm doing something like the following, but would prefer to avoid the temporary variable `recursive_ols_doc` if possible (for style reasons, if nothing else), and without writing the documentation in a separate file. recursive_ols_doc = Calculates the OLS estimators for the model y ~ x recursively... * `recursive_ols` is a wrapper that works like this... * `recursive_ols!` does all the real work like that... @doc recursive_ols_doc - function recursive_ols!(estimates::Array, y, x) ## Calculations end @doc recursive_ols_doc - function recursive_ols(y, x, R::Integer) ## preallocate, then call recursive_ols! end Thanks! (Really liking this documentation tool, btw)
Re: [julia-users] Is there a natural way to use the same docstring for multiple functions?
It's not what you are asking, but Lexicon/Docile has a couple of nice features for grouping doc strings. First, to document a generic function before it's defined, you can do: My doc string here :genericfun genericfun(x::something1) = 1 genericfun(x::something2) = 2 You can also define a docstring that applies to a set of methods as: My doc string here (getindex, :MyType, Any...) Both are good ways to group functions you define. On Tue, Jan 13, 2015 at 4:00 PM, Gray Calhoun gcalh...@iastate.edu wrote: Oh, perfect. The @doc (@doc ) construction is exactly what I was looking for. Thanks! On Tuesday, January 13, 2015 at 2:35:09 PM UTC-6, Mike Innes wrote: That should pretty much work as is, but you'll want to use the `doc` string macro for markdown formatting, i.e. recursive_ols_doc = doc The other thing you can do is document one function, then retrieve that functions docs with the @doc macro: @doc foo - function recursive_ols() ... @doc (@doc recursive_ols) - function recursive_ols!() ... On 13 January 2015 at 19:49, Gray Calhoun gcal...@iastate.edu wrote: Hi everyone, quick question about docstrings. Sometimes it makes sense to use the same help text for different functions; I'm particularly thinking mutating and non-mutating versions of the same algorithm. Is there a natural way to reuse a docstring for different functions (either in Docile.jl or in v0.4 base)? Specifically, I'm doing something like the following, but would prefer to avoid the temporary variable `recursive_ols_doc` if possible (for style reasons, if nothing else), and without writing the documentation in a separate file. recursive_ols_doc = Calculates the OLS estimators for the model y ~ x recursively... * `recursive_ols` is a wrapper that works like this... * `recursive_ols!` does all the real work like that... @doc recursive_ols_doc - function recursive_ols!(estimates::Array, y, x) ## Calculations end @doc recursive_ols_doc - function recursive_ols(y, x, R::Integer) ## preallocate, then call recursive_ols! end Thanks! (Really liking this documentation tool, btw)
Re: [julia-users] Is there a natural way to use the same docstring for multiple functions?
That should pretty much work as is, but you'll want to use the `doc` string macro for markdown formatting, i.e. recursive_ols_doc = doc The other thing you can do is document one function, then retrieve that functions docs with the @doc macro: @doc foo - function recursive_ols() ... @doc (@doc recursive_ols) - function recursive_ols!() ... On 13 January 2015 at 19:49, Gray Calhoun gcalh...@iastate.edu wrote: Hi everyone, quick question about docstrings. Sometimes it makes sense to use the same help text for different functions; I'm particularly thinking mutating and non-mutating versions of the same algorithm. Is there a natural way to reuse a docstring for different functions (either in Docile.jl or in v0.4 base)? Specifically, I'm doing something like the following, but would prefer to avoid the temporary variable `recursive_ols_doc` if possible (for style reasons, if nothing else), and without writing the documentation in a separate file. recursive_ols_doc = Calculates the OLS estimators for the model y ~ x recursively... * `recursive_ols` is a wrapper that works like this... * `recursive_ols!` does all the real work like that... @doc recursive_ols_doc - function recursive_ols!(estimates::Array, y, x) ## Calculations end @doc recursive_ols_doc - function recursive_ols(y, x, R::Integer) ## preallocate, then call recursive_ols! end Thanks! (Really liking this documentation tool, btw)
