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