Some way to link comments to Julia constructs

[kk49]

Maybe a ##! comment before or on same line as a type/method/etc... get linked to type/method/etc...

These comments could then be printed from the command line. If something like the doxygen convention is followed, Julia could eventually be processed by doxygen.

[pao]

See also #720.

[JeffBezanson]

Nothing wrong with processing julia source with some external tool, but we're pretty sure we're not going to build anything into the language around this.

[kk49]

I agree, I not asking for a change to the language, but I would like a standard to follow, so that my code (and others) follows what the language developers are doing.

[StefanKarpinski]

For now, comments are just plain old comments — intended only for readers of the code. Library documentation lives in sphinx and the manual lives on the website. Maybe we'll get more integration going forward, but for now it's pretty fast and loose.

[JeffBezanson]

Check out https://github.com/lcw/jocco.

[stevengj]

Still need this. I agree that this probably shouldn't be part of the Julia language per se, but it would be good to:

• "Bless" some standard tool by using it in JuliaLang and in particular in the Julia standard library.
• Rather than roll our own, adopt a mature and popular tool (e.g. Doxygen) and submit patches to make it work better with Julia (both syntactically and also for unusual semantic features like multiple dispatch). (Note that we need a tool that supports LaTeX equations, in order to properly document the mathematical functionality that is Julia's initial focus.)
• Integrate that with the help documentation. (Currently, we have to document every function twice, which is unacceptable.)

The longer we continue with ad hoc documentation systems, the messier our situation becomes and the harder it will be to retrofit a more usable tool.

[StefanKarpinski]

I think there are two issues:

1. A mechanism for making the contents of comments associated with code available to the running program.
2. Interpretation of that data as some help system.

We should focus first on the mechanism and make that happen and then play around with various approaches to interpretation and presentation. The former is also something that arguably makes sense as part of the language, while the second is more of an ecosystem question.

[johnmyleswhite]

I'd be strongly in favor of adopting something based on Doxygen. I've been thinking about this issue a lot recently and always find myself coming back to the basic ideas in Doxygen.

For me, the most important thing (and something I've already started working on) is having a tool that will automatically generate skeletal documentation for existing code.

[stevengj]

@johnmyleswhite, can you hack together a prototype with Doxygen just so that we can get a sense of what it looks like? My main concern about Doxygen is that it seems oriented toward single dispatch, but perhaps we can massage it into something that works for us.

[johnmyleswhite]

Yes, I'll do that this week.

[stevengj]

The main competitor to Doxygen seems to be Sphinx. We are already using its RST formats, but we would need to roll our own way to extract it from the source.

[johnmyleswhite]

I think rolling our own way to extract formatted comments from source is not going to be that difficult: R did it for its roxygen2 package.

For me, the problem with our current use of Sphinx is that we tend to use it more for formatting than for structure. What I like about Doxygen is that it encourages you to write out a proper database about each function instead of hoping that you'll follow the right notational convention to indicate things like the return type signature.