This debate seems a little premature to me since the definition of @doc is not totally finished yet and we need to finalize that before anyone should be adding documentation to 0.3 packages.
-- John On Dec 17, 2014, at 3:15 PM, Seth <[email protected]> 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/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
