Just add this to your modules:
if VERSION < v"0.4.0-dev"
using Docile
end
and use the subset of @doc common to 0.3 and 0.4.
--Tim
On Wednesday, December 17, 2014 12:15:03 PM Seth wrote:
> +1. Please reconsider making a @doc (at least a NOP) for 0.3.x - this way
> we can start writing repl-printable docstrings that will be useful in 0.4
> but not have our code break in earlier versions.
>
> On Tuesday, December 16, 2014 4:50:56 PM UTC-8, [email protected] wrote:
> > So if otherwise unchanged code is documented with @doc (which it will be,
> > who doesn't want it to show in the repl :) then it won't compile on 0.3?
> >
> > If it won't compile it makes maintaining backward compatibility harder,
> > and its hard enough between 0.4 and 0.3 already.
> >
> > On Wednesday, December 17, 2014 9:04:53 AM UTC+10, Mike Innes wrote:
> >> It is needed if you want the docs to show up in the repl etc. It's just
> >> that the plain string won't break anything (it won't do anything, either,
> >> for now).
> >>
> >> On 16 December 2014 at 22:58, <[email protected]> wrote:
> >>> On Wednesday, December 17, 2014 8:41:00 AM UTC+10, Mike Innes wrote:
> >>>> It's not really that worthwhile since (a) you can use Docile and (b)
> >>>> the future syntax
> >>>>
> >>>> """
> >>>> foo
> >>>> """
> >>>> foo() ...
> >>>>
> >>>> is backwards-compatible already. I just use that.
> >>>
> >>> Oh, ok, I thought an @doc macro was needed in 0.4
> >>> https://github.com/JuliaLang/julia/blob/d0a951ccb3a7ebae7909665f4445a019
> >>> f2ee54a1/base/basedocs.jl .
> >>>
> >>> Cheers
> >>> Lex
> >>>
> >>>> On 16 December 2014 at 22:37, <[email protected]> wrote:
> >>>>> Since the @doc is 0.4, is it possible to backport a "do nothing"
> >>>>> version that will allow documented code to still compile in 0.3?
> >>>>>
> >>>>> Cheers
> >>>>> Lex
> >>>>>
> >>>>> On Wednesday, December 17, 2014 8:04:06 AM UTC+10, Mike Innes wrote:
> >>>>>> Actually the @doc macro will still interpret plain strings as
> >>>>>> markdown by default. There are some caveats with escaping that make
> >>>>>> it good
> >>>>>> practice to write doc"" anyway, but those will go away once the
> >>>>>> parser
> >>>>>> changes are implemented.
> >>>>>>
> >>>>>> I'm in the process of writing documentation documentation, so the
> >>>>>> manual should be up to date reasonably soon.
> >>>>>>
> >>>>>> On 16 December 2014 at 21:55, Ivar Nesje <[email protected]> wrote:
> >>>>>>> > Hi,
> >>>>>>>
> >>>>>>> Hello.
> >>>>>>>
> >>>>>>> > Looks like exciting doc changes are afoot with Julia! I'd like to
> >>>>>>>
> >>>>>>> get some more understanding of what's coming. Had a look at some of
> >>>>>>> the
> >>>>>>> github issues tagged "doc", but I'm still missing some basics (note,
> >>>>>>> I'm
> >>>>>>>
> >>>>>>> still quite new to Julia). Questions:
> >>>>>>> * Is code from Docile.jl, Lexicon.jl, and Markdown.jl being used /
> >>>>>>>
> >>>>>>> incorporated into Julia proper?
> >>>>>>>
> >>>>>>> Yes.
> >>>>>>>
> >>>>>>> * Will the new syntax be `doc "..."`, `@doc "..." ->`, or
> >>>>>>>
> >>>>>>> something else?
> >>>>>>>
> >>>>>>> The -> is probably going away, but final syntax is not yet set in
> >>>>>>> stone (nor in code).
> >>>>>>>
> >>>>>>> * What is `md"Some *text* here`? Will Julia support and/or require
> >>>>>>>
> >>>>>>> that for the new docstrings? If so, what is the benefit of
> >>>>>>> `md"this"` over
> >>>>>>> `"this"`?
> >>>>>>>
> >>>>>>> The benefit is that `md"this"` has an explicit format, so that we
> >>>>>>> can have more formats in the future. The value has been discussed
> >>>>>>> and you
> >>>>>>> can have different formats by other means. I like the way it makes
> >>>>>>> markdown
> >>>>>>> optional, but others want to save two characters to type.
> >>>>>>>
> >>>>>>> * Regarding the docs currently at <http://docs.julialang.org/en/
> >>>>>>>
> >>>>>>> release-0.3/>, does all of that content currently come only from
> >>>>>>> the contents of julia/doc and below?
> >>>>>>>
> >>>>>>> Yes
> >>>>>>>
> >>>>>>> * Will the docstrings in 0.4 be online at, say,
> >>>>>>>
> >>>>>>> http://docs.julialang.org/en/release-0.4/ , integrated with the
> >>>>>>> rendered .rst docs? Or are they intended to be strictly available
> >>>>>>> via the
> >>>>>>> repl? Hm... to avoid duplication, are any files in julia/doc slated
> >>>>>>> to be
> >>>>>>> diced up, reformatted into markdown, and inserted into source as
> >>>>>>> docstrings?
> >>>>>>>
> >>>>>>> Maybe, but it's hard to predict the future. Many files in Base are
> >>>>>>> too long already, and detailed docs will not make them shorter. For
> >>>>>>> huge
> >>>>>>> codebases, I think it makes sense to fit as much code as possible on
> >>>>>>> a
> >>>>>>> screen, and search in separate docs if I need to know more about a
> >>>>>>> function.
> >>>>>>>
> >>>>>>> Thanks,
> >>>>>>> -- John
