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/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 >>>>> >>>>
