summarize the methods rather than paste them with all the type information
At the moment, yes. Having things a little bit more automated to avoid signatures becoming out-of-sync with the methods would definitely be good to have at some point though. — Mike On Sunday, 25 October 2015 15:34:07 UTC+2, Cedric St-Jean wrote: > > Thank you for the detailed answer! It makes sense. Looking at the docs for > built-ins, I take it that good Julia documentation style should summarize > the methods rather than paste them with all the type information, but it's > cool that it's a possibility. > > On Sunday, October 25, 2015 at 3:15:54 AM UTC-4, Michael Hatherly wrote: >> >> Is it an oversight that ?draw_rectangle does not show methods if a >> docstring is present >> >> It’s the expected behaviour. >> >> If you’d like to have a method table show up when searching for function >> docs then you can do something like >> >> module M >> >> """ >> f(x) >> >> ... >> """ >> f(x) = x >> >> """ >> f(x, y) >> >> ... >> """ >> f(x, y) = x + y >> >> f(x, y, z) = x + y - z >> >> """ >> # Function List >> ``` >> $(methods(f)) >> ``` >> """ >> f >> >> end >> >> Note that the docs for f must be added after every method is defined so >> that they all show up in methods(f). >> >> Then when searching for M.f you’d get >> >> help?> M.f >> f(x, y) >> >> ... >> >> f(x) >> >> ... >> >> Function List >> ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ >> >> # 3 methods for generic function "f": >> f(x) at /home/mike/M.jl:8 >> f(x, y) at /home/mike/M.jl:15 >> f(x, y, z) at /home/mike/M.jl:17 >> >> When searching for individual methods the method list won’t show up >> though: >> >> help?> M.f(::Any) >> f(x) >> >> ... >> >> help?> M.f(1, 2) >> f(x, y) >> >> ... >> >> — Mike >> >> On Sunday, 25 October 2015 04:13:58 UTC+2, Cedric St-Jean wrote: >> >> A lot of my documentation looks like this: >>> >>> """ Draws a rectangle of size `(width, height)` and color `color`""" >>> function draw_rectangle(width::Int, height::Int; color="black") >>> ... >>> end >>> >>> The interactive help ?draw_rectangle shows: >>> >>> search: >>> >>> Draws a rectangle of size (width, height) and color color >>> >>> draw_rectangle >>> >>> >>> Unfortunately, this is missing the type information and method list. In >>> contrast, if I didn't specify a docstring, ?draw_rectangle_ yields >>> >>> draw_rectangle_ is a generic Function. >>> # 1 method for generic function "draw_rectangle_": >>> draw_rectangle_(width::Int64, height::Int64) at In[72]:2 >>> draw_rectangle_ draw_rectangle >>> >>> This is obviously useful information, and I'd like to see both the >>> docstring and the list of methods. Is it an oversight that ?draw_rectangle >>> does not show methods if a docstring is present, or is there a convention >>> that the method list should be replicated inside the docstrings somehow? >>> >>> Cédric >>> >> >> >
