A thing that works well in R is that arguments to functions have a separate markup. When you use e.g. roxygen to write documentation, the @params and @return elements make it clear what is what. This is something I find lacking in Julia / Lexicon.jl
(and implementing it goes very much over my head) This being said, I find the julia manual superior to R documentation: the fact that all functions doing similare things are on the same page made me realize there are better alternatives often. t Michael Borregaard (12/02 05:08): > Maybe a good time to repost this link: > https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#improving-documentation > > <https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2FJuliaLang%2Fjulia%2Fblob%2Fmaster%2FCONTRIBUTING.md%23improving-documentation&sa=D&sntz=1&usg=AFQjCNFSu7VhGC5GE6j_5KDAKIdtnBsG4Q> > > As I understand it, the julia documentation format is still an evolving > entity. Google-searching in R works well because of the massive number of > google searches / site visits to R pages. When I started using R, during my > PhD in 2006, it was almost impossible to google R functions, and there were > all kinds of (not very functional) search engines to bring up R results. > Today everybody just googles it. I feel completely confident that julia > will have the same development, and a lot faster. > > Den fredag den 12. februar 2016 kl. 13.16.08 UTC+1 skrev J Luis: > > > > One main 'dislike' I find in the documentation is that, contrary to Matlab > > and R examples that have one page for each function, in julia we have lots > > of functions per page with short and often cryptic descriptions. Example > > > > std(*v*[, *region*]) > > > > Compute the sample standard deviation of a vector or array v, optionally > > along dimensions in region. > > > > To have longer and, VERY IMPORTANT, usage examples one need a per function > > page manual. > > > > sexta-feira, 12 de Fevereiro de 2016 às 11:10:54 UTC, Milan Bouchet-Valat > > escreveu: > >> > >> Le vendredi 12 février 2016 à 09:51 +0100, Michele Zaffalon a écrit : > >> > But the original point is still valid: using the search box in the > >> > official documentation page http://docs.julialang.org/en/release-0.4, > >> > searching for "standard deviation" does not bring up any useful hit, > >> > despite the fact that Base.std is fairly well documented and contains > >> > the words standard deviation. > >> > Is there a reason why it should work at the REPL but not in the > >> > webpage? > >> Searching for "deviation" works, so it's quite mysterious that > >> "standard deviation" doesn't... Looks like a bug in the Sphinx search > >> engine. > >> > >> Google's behavior is really weird too. Even a query like "standard > >> deviation julia site:docs.julialang.org" gives the manual page home for > >> the standard library first (even if it doesn't contain "deviation"), as > >> well as pages mentioning "standard error". Maybe some pages are not > >> indexed at all? Could something be tweaked in the Sphinx configuration? > >> > >> > >> Regards > >> > >> > > >> > On Fri, Feb 12, 2016 at 9:25 AM, Mauro <[email protected]> wrote: > >> > > Also at the Julia REPL: > >> > > > >> > > julia> apropos("standard deviation") > >> > > randn! > >> > > stdm > >> > > std > >> > > randn > >> > > > >> > > help?> std > >> > > search: std stdm STDIN STDOUT STDERR setdiff setdiff! hist2d > >> > > hist2d! stride strides StridedArray StridedVector StridedMatrix > >> > > StridedVecOrMat redirect_stdin > >> > > > >> > > std(v[, region]) > >> > > > >> > > Compute the sample standard deviation of a vector or array v, > >> > > optionally along dimensions in region. The algorithm returns an > >> > > estimator of the generative > >> > > distribution's standard deviation under the assumption that > >> > > each entry of v is an IID drawn from that generative distribution. > >> > > This computation is equivalent to > >> > > calculating sqrt(sum((v - mean(v)).^2) / (length(v) - 1)). > >> > > Note: Julia does not ignore NaN values in the computation. For > >> > > applications requiring the handling of > >> > > missing data, the DataArray package is recommended. > >> > > > >> > > Having said this, documentation always needs improvements and is > >> > > certainly not on Matlab's level of completeness. Please contribute > >> > > where you find it lacking. See > >> > > https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#impr > >> > > oving-documentation > >> > > > >> > > > >> > > On Fri, 2016-02-12 at 09:18, NotSoRecentConvert <[email protected]> > >> > > wrote: > >> > > > You can even download the entire thing as a PDF, HTML, or EPUB if > >> > > you want > >> > > > to highlight, annotate, or bookmark your most searched functions. > >> > > Look in > >> > > > the lower right of the page for "v: latest" and click it for more > >> > > options. > >> > > > > >> > > > On Friday, February 12, 2016 at 8:03:27 AM UTC+1, Lutfullah Tomak > >> > > wrote: > >> > > >> > >> > > >> There is this one > >> > > >> > >> > > >> http://docs.julialang.org/en/release-0.4/stdlib/math/#Base.std > >> > > >> > >> > > >> Instead of google, I use this manual for search. > >> > > >> > >> > > >> > >> > > > >> > > -- Timothée Poisot, Ph.D. Professeur adjoint Quantitative and Computational Ecology Department of Biological Sciences Université de Montréal WEB http://poisotlab.io/ TWITTER @PoisotLab
