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