Docile and Julia 0.4

[tshort]

I don't understand the path forward with Docile and how it will work with the Base @doc functionality. I've seen the suggestions to check Julia's version number to decide whether to import Docile.

Is Docile meant to be fully replaced by the @doc functionality in Base?

Can Docile be used alongside the Base functionality? The @doc macro conflicts, but I haven't tested it beyond that.

If I want to use the extended functionality of Docile in a package, can I use that, or will Base stomp on that in 0.4? I'd like to use the external file referencing feature and maybe the meta feature.

[MichaelHatherly]

As far as I'm aware the plan is to eventually have Docile superseded by the @doc in Base. Some of the extra features in Docile weren't added since there didn't seem to be a great demand for them at the time.

I'm haven't managed to work out a way to get the two @doc macros to play nicely together. Apart from the @doc* syntax and meta they should work the same though. You might be able to use the full name for the macro (Docile.@doc) where you'd like to use meta for external file referencing, though I haven't tried doing that yet and you'll end up with docs stored in different places.

From what I've gathered the plan is to do away with the macro all together and rather use plain strings above methods, types etc. to document them. That's not available in Base yet. (Edit: JuliaLang/julia#8965).

I've recently got the equivalent syntax working in Docile master branch. There may still be a few issues with it though and Lexicon/Docile interaction may be slightly broken when using it.

[tshort]

Thanks. This issue can be closed. It seems like a step down. For me, the main things lacking in Base are:

• @doc* - I've used it more than @doc.
• Pointers to the source.
• Full-text searches.

[MichaelHatherly]

To cover the first use case, you can do (in Docile and 0.4):

foobar(x) = x

@doc "docs for foobar" ->
foobar

That's a little bit annoying and the main reason the * syntax came about in #30. JuliaLang/julia#8283 suggests a syntax that would allow writing the documentation before any of the method definitions.

The other two points are probably worth raising over in the julia repo if there's not issues for them yet.

[MichaelHatherly]

So I've just pushed a special syntax to allow for documenting a generic function before it's been defined:

using Docile
@document

"docs for generic function"
:foobar

foobar(x) = x

Not perfect, but does the job with the new style plain docstrings.

[tshort]

I like your special syntax for generic functions.

On Tue, Jan 6, 2015 at 3:15 AM, Michael Hatherly notifications@github.com
wrote:

Closed #56 #56.

—
Reply to this email directly or view it on GitHub
#56 (comment).

[hayd]

It would be great to have a central issue for how to get these awesome changes into base (presumably in 0.5). Very exciting you can do this new syntax!

Am I right in reading that you no longer even need using Docile in your module to get docstrings (Just use the string syntax, and when you want to look up the doc then Docile finds/parses the docstring)??

[MichaelHatherly]

how to get these awesome changes into base

I've avoided making an effort to get things integrated into base since there's still work to be done in places. Once that's done then yes, getting this better integrated would be good. Perhaps with precompilation and default packages Docile wouldn't even need to be part of base and could retain it's current release cycle (weeks instead of months).

Am I right in reading that you no longer even need using Docile in your module

That's correct, when using Lexicon's ? mode Docile will just extract docstrings from any loaded package (base as well if you call Docile.Cache.togglebase()) automatically.