As an interaction designer I think there could also be another way to approach this problem - from the user's point of view.
I'd say there's two users to keep in mind here: - the person who writes the documentation - the person who reads the documentation We need to ask: when will the users want do this, and how? In the readers case, there's plenty of places. When looking up what a function does in IJulia - nice formatting, searchability a la Hoogle seem valuable here. When reading the source code of a .jl code directly is also an option. Then we want to have a convention that ensures the documentation is nicely laid out among the code - comment-based documentation with a convention that guides good code commenting (a la Go) makes more sense here. In the writers case, perhaps in the repl? Then a macro attaching documentation to an existing function makes sense. In a .jl source file? In the latter case, I think it makes more sense to have the documentation right next to the thing being documented, following a sensible convention for readability.
