In the recent giant thread on Julia popularity, and in the recent user/developer survey, the topic of documentation often comes up. Usually when people bring it up, they focus on things for brand new users – guides, blogs, etc. Focusing on new users is great, but as someone who’s no longer quite a…

[image] ForceBru: I think it’s very useful to do ?func (which is the equivalent of Python’s help(func)) and see the function’s signature, like in Python. As you already demonstrated, help mode prints methods(func) if it can’t find any docstrings. If there is a docstring, you use that to mindf…

[image] Benny: You picked a really bad example because you can’t put graphs or any images in a docstring. I just tried it and it turns out you can put images in a docstring. """ adsf(x) = 1 ![](https://global.discourse-cdn.com/julialang/original/2X/1/12829a7ba92b924d4ce81099cbf99785bee9b405…

[image] ForceBru: Python does it right Well, Python does it right for Python, but not for Julia. The complicating factor is multiple dispatch. Consider this fairly common pattern: """ ```julia solve(problem; method=:auto, kwargs...) ``` solves the given `problem` using `method`. All oth…

The problem is also on which level of abstraction the return should or can be specified. While it might be true that 1 + 2 returns an Int64 this might not be important. Instead, I usually want to know which operations I can assume on the returned value, i.e., when working with matrices and vectors A…

[image] jar1: showing the doc in the vscode side panel It doesn’t happen if you retrieve a docstring with @doc or print it in help mode, you just see (Image : ). You need something that can handle links and render an image retrieved from one. That is a nice VScode feature but developers can’t…

I don’t think old-school platform limitations should inhibit documentation. Emacs can show images, I assume many other editors can too. We’ve been through this for unicode - we can do it again for graphics.

It’s not an “old-school” issue, it’s a standardization issue. A feature shouldn’t work in one place (display an image from a link in VScode) and be broken in another (print (Image : ) in the REPL’s help mode). It doesn’t seem straightforward to bring the REPL up to par either, terminals in general a…

In the documentation of the greater than operator >, it can be mentioned that > can be chained like 1 > x > -1.

One of the examples does show this, but if you feel that it can be clearer then open an issue at Issues · JuliaLang/julia · GitHub with your exact proposed change (If you can, then a pull request would be better).

Maybe by adding a comment to it like julia> 7 > 3 > 1 # equivalent to 7 > 3 && 3 > 1 true

Some thoughts on improving basic function documentation

General Usage

PetrKryslUCSD October 21, 2024, 2:08pm 52

GD is you

Topic		Replies	Views
The challenges of documenting generic functions General Usage documentation	24	1472	August 29, 2023
Argument-specific docstrings or comments Internals & Design	23	2962	March 2, 2026
Coordinating community efforts to enrich function docs General Usage	44	2111	May 2, 2022
Documenter.jl: How to avoid repetitions of shared docstrings? General Usage documenter	11	399	May 11, 2025
Blog post about my experiences with Julia Community	259	16924	June 19, 2022

Some thoughts on improving basic function documentation

Related topics