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] <javascript:>> 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/d0a951ccb3a7ebae7909665f4445a019f2ee54a1/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 >>>>>> >>>>>
