WIP: documentation improvements

[dirk]

Have some free time right now so I'm working on improving the documentation. Please let me know if there are any specific functions/modules/etc. that have been updated/added that need documenting!

NOTE: This also now includes a small fix to the TextMate bundle to include a capture for nothing, true, false, etc.

[stevengj]

See #2145 : it would be good to note that ccall supports structs, and that Complex64 and Complex128 arguments passed/returned by value (but not as arrays or otherwise by reference) should use ComplexPair{Float32} and ComplexPair{Float64}, respectively.

[nolta]

Why were these deleted?

[dirk]

Not sure. Thanks for pointing that out! I'll add them back in.

[dirk]

@stevengj Thanks for the suggestions. I'll work on that tonight.

[stevengj]

Another documentation omission if you are in the mood: #2159.

[kmsquire]

Hi Dirk, if you're still working on this:

• doc/manual/sparse-matrices.rst needs to be included in index.rst
• sorting has recently gone through a major overhaul, most of the specialized sorting functions no longer exist and should be removed from the documentation. The signatures of the sort functions themselves have also changed somewhat.
• if you have the proper tools installed, you could regenerate the help database with cd doc; make helpdb.jl, and add it to the commit.

Cheers!

[ViralBShah]

I tried to make sparse matrices a part of arrays - but was not too successful at it.

[kmsquire]

If you update the sort docs, @StefanKarpinski should know. There may be some additional changes coming up.

[dirk]

@kmsquire: I'll update the sort docs and look into sparse matrices too.

[kmsquire]

Thanks!

[timholy]

Wow, this is impressive.

I doubt we should bikeshed this, it seems so clearly an improvement that perhaps we should just take it and deal with problems later?

[JeffBezanson]

Sorry, we collided a bit.

[kmsquire]

I got the basic information for the sort docs done (#2291, #2294).

You might consider renaming this to RFC, so that it gets considered for the 0.1 release (though it might be too late for that), and then start another pull if you plan to work on the docs more. Thanks for working on this!

[timholy]

@dirk, I made some changes. In particular, there were some places, e.g., iterable{Type} where I did not think the extra information actually clarified the meaning. So I deleted those, hope that's OK.

[dirk]

@timholy Yeah, no problem! Thanks for getting this merged in.

I'm going to keep chipping away on this and #2242. So it'll probably be reopened in a little with some more commits if that's alright.

[pao]

@dirk, you'll probably be better off rebasing on master on or after bf3eccf, then opening a new pull request.

[timholy]

Please open as a new pull request against fresh master. It took me quite a
long time to clean this up, I wouldn't want to have to go through it again.

[dirk]

@timholy & @pao: Will do. Sorry about all the cleanup you had to do. Know that pain from having to merge edits to the docs while I was working on this.

[timholy]

@dirk, I'm no git expert, but my impression is that unless you think someone will branch off your tree, you can update your pull request by rebasing your commits against a fresh master and doing a force push to your public repository. Others should contradict this if it is bad advice.

[dirk]

@timholy: Yeah that's what I've been trying to do. But there were some other edits to doc/base.rst here and there that got pushed to master while I was working so I still had to do some pesky merges.

[pao]

Sometimes the best thing to do is rebuild the patches back onto master:

$ git branch mybranch-backup
$ git reset origin/master #assuming JuliaLang/julia is origin
$ git add -p #stage the parts of your first patch
$ git commit
$ git add -p #stage the parts of your second patch
$ git commit
...
$ git push -f mine HEAD #to push your cleanly-applicable patch queue to your fork

[dirk]

@pao: Gotcha, will do.