I respectfully disagree. I would agree with you if your statement concluded "before anyone should be adding documentation to ANY packages", but the thing is, @doc is available for use in 0.4 and, while the definition may change, it's merely a matter of break-fix if the format changes so much between now and when it's "ready" that @docstrings fail to compile properly. However, RIGHT NOW, any code written with @doc in a 0.4 environment will simply fail in 0.3, Compat or no Compat.
My suggestion would be to create, if possible, a @doc noop in Compat.jl so that seasoned developers who are using the latest and greatest 0.4 code can start creating documentation now* while not breaking their packages for those users who are on the release version, and folks who are developing on 0.3 can include basic @docstrings that will work as intended on 0.4. *the reality is that documentation is frequently seen as an irritation for developers, especially once a package is released. Getting them to add @doc after they've moved on to the next thing requiring their attention, and getting end users to update their packages just to get new docstrings, is going to be a bigger challenge than providing the capability at the front end and encouraging its use. On Wednesday, December 17, 2014 12:17:33 PM UTC-8, John Myles White wrote: > > 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] <javascript:>> > 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 >>>>>>>> >>>>>>> >
