Moved so many docs out of HelpDB. More examples. #18041

kshyatt · 2016-08-15T22:14:31Z

I'm sorry this is so huge. Once I started, I couldn't stop. Doctests passed locally.

tkelman · 2016-08-16T15:20:11Z

base/array.jl

+    splice!(a::Vector, index::Integer, [replacement]) -> item
+
+Remove the item at the given index, and return the removed item. Subsequent items are
+shifted down to fill the resulting gap. If specified, replacement values from an ordered


which way is "down"?

kshyatt · 2016-08-16T23:12:01Z

Doctests again passed locally.

MichaelHatherly · 2016-08-17T06:10:30Z

base/file.jl

+        cd(f::Function, dir::AbstractString=homedir())
+
+    Temporarily changes the current working directory and applies function `f` before returning.
+    """ ->


Probably simpler to put the docs that have OS-specific definitions after the if blocks using the same syntax that was being used in the helpdb. Same with the other ones further down. That would avoid having to always check whether all the duplicates get updated when changes are made to one of them.

Fixed in latest. Anything else I should look after?

There's a couple more duplicated @docs that can get the same treatment as cd, but other than that I didn't notice anything else out of place.

I'm still double-checking this, so may be good to wait for another set of eyes since backporting this might allow migration of the manual to be done in an automated way on both master and 0.5.

good to wait for another set of eyes

Yes, definitely.

might allow migration of the manual to be done in an automated way on both master and 0.5.

At the moment the translation scripts I'm using do seem to work fine against master and 0.5, though keeping things in sync as much as possible would be greatly appreciated.

kshyatt · 2016-08-19T19:14:53Z

@MichaelHatherly if you can point out specific spots I don't need to @doc I would be super grateful but if you're too busy/don't feel like it I can also just grep the diff.

MichaelHatherly · 2016-08-19T20:39:42Z

if you can point out specific spots I don't need to @doc I would be super grateful

Sure, can do. Would you rather have inline comments here pointing out the spots, or I can make a quick diff of the changes that you can just apply?

kshyatt · 2016-08-19T20:49:10Z

The diff option sounds like a way to learn something new, so let's go with that!

MichaelHatherly · 2016-08-19T20:56:12Z

https://gist.github.com/MichaelHatherly/cc9f1ce532e9f851ff6906815e517775

I've not yet compiled those changes since LLVM decided it was a good time to need recompiling... but I think the changes should be good.

kshyatt · 2016-08-19T21:07:20Z

Thanks, @MichaelHatherly. make docs && make -C doc doctest passed happily.

ViralBShah · 2016-08-20T07:03:59Z

This is impressive work! @tkelman What's the right strategy here? Merge and backport, or hold out until the 0.5 release is out and leave this on master?

After this is merged, future doc improvements will be difficult to backport to 0.5, and perhaps for that reason, backport is desirable. Just thinking out aloud.

tkelman · 2016-08-20T07:09:00Z

Finish double-checking it then merge and backport.

MichaelHatherly · 2016-08-20T09:33:48Z

For functions that are just aliases of other functions, such as ÷, the docs should be added to the "real" definition rather than the const ... def. This is because the docsystem can easily find the "real" function given any alias of it, but it can't go the other way since a function might have several aliases.

For example on this branch searching for docs on ÷ and div don't return the same thing, whereas on master they do.

(This is probably worth mentioning in the docsystem docs. I'll write something up for the docs later today or tomorrow.)

The aliases that should be changed are:

% to rem;
.≠ to .!=;
.≤ to .<=;
÷ to div;
∈ to in;
≡ to is.

MichaelHatherly · 2016-08-20T09:34:01Z

doc/stdlib/io-network.rst


   .. Docstring generated from Julia source

-   Replace ``STDOUT`` by stream for all C and Julia level output to ``STDOUT``\ . Note that ``stream`` must be a TTY, a ``Pipe`` or a ``TCPSocket``\ .
+   Create a pipe to which all C and Julia level :obj:`STDOUT` output will be redirected. Returns a tuple ``(rd, wr)`` representing the pipe ends. Data written to :obj:`STDOUT` may now be read from the ``rd`` end of the pipe. The ``wr`` end is given for convenience in case the old :obj:`STDOUT` object was cached by the user and needs to be replaced elsewhere.


Duplicate redirect_stdout signatures here.

As mentioned in JuliaLang#18041 (comment) docstrings attached to aliases of functions should be avoided where possible.

As mentioned in #18041 (comment) docstrings attached to aliases of functions should be avoided where possible.

As mentioned in #18041 (comment) docstrings attached to aliases of functions should be avoided where possible. (cherry picked from commit 3ed55a4)

kshyatt · 2016-08-23T00:49:02Z

Doctests passed locally. I took CI skip off since I rebased. @MichaelHatherly is this ok assuming lights turn green?

tkelman · 2016-08-23T01:05:41Z

I only got a small way through reviewing this before backporting got in the way. planning on doing the rest tomorrow.

tkelman · 2016-08-31T18:30:32Z

base/file.jl

+"""
+    readlink(path::AbstractString) -> AbstractString
+
+Returns the value of a symbolic link `path`.


(readlink docstring) is "the value of a symbolic link" unambiguous? maybe worth rewording to say something like "the target location a symbolic link points to" ?

tkelman · 2016-09-01T21:08:33Z

doc/stdlib/io-network.rst


   .. Docstring generated from Julia source

-   Display an informational message. Argument ``msg`` is a string describing the information to be displayed.
+   Display an informational message. Argument ``msg`` is a string describing the information to be displayed. The ``prefix`` kwarg can be used to override the default prepending of ``msg``\ .


(info docstring) spell out kwarg ?

kshyatt · 2016-09-03T03:23:03Z

@tkelman thoughts?

tkelman · 2016-09-03T15:38:52Z

Let's get it merged. Did you want to do a rebase to clean up the history?

kshyatt · 2016-09-03T15:41:59Z

Will do when I get home

On Sat, Sep 3, 2016, 8:38 AM Tony Kelman notifications@github.com wrote:

Let's get it merged. Did you want to do a rebase to clean up the history?

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#18041 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAyk47DThcmzwZ4Z27u6Pk9ZYEZC_HeXks5qmZSRgaJpZM4Jk0zM
.

tkelman · 2016-09-03T17:32:29Z

do the honors?

kshyatt · 2016-09-03T17:33:17Z

🎉

As mentioned in JuliaLang#18041 (comment) docstrings attached to aliases of functions should be avoided where possible.

kshyatt added the domain:docs This change adds or pertains to documentation label Aug 15, 2016

kshyatt force-pushed the ksh/docamputation branch from 297df7c to 983b524 Compare August 15, 2016 22:25

tkelman reviewed Aug 16, 2016
View reviewed changes

MichaelHatherly reviewed Aug 17, 2016
View reviewed changes

kshyatt force-pushed the ksh/docamputation branch from 5bd914c to dc30b82 Compare August 19, 2016 21:52

ViralBShah added the backport pending 0.5 label Aug 20, 2016

MichaelHatherly reviewed Aug 20, 2016
View reviewed changes

MichaelHatherly added a commit to MichaelHatherly/julia that referenced this pull request Aug 20, 2016

Add note about docstrings for aliases

ad26747

As mentioned in JuliaLang#18041 (comment) docstrings attached to aliases of functions should be avoided where possible.

MichaelHatherly mentioned this pull request Aug 20, 2016

Add note about docstrings for aliases #18157

Merged

tkelman pushed a commit that referenced this pull request Aug 21, 2016

Add note about docstrings for aliases (#18157)

3ed55a4

As mentioned in #18041 (comment) docstrings attached to aliases of functions should be avoided where possible.

tkelman pushed a commit that referenced this pull request Aug 21, 2016

Add note about docstrings for aliases (#18157)

285ef3e

As mentioned in #18041 (comment) docstrings attached to aliases of functions should be avoided where possible. (cherry picked from commit 3ed55a4)

kshyatt force-pushed the ksh/docamputation branch from bba01c4 to 5131751 Compare August 23, 2016 00:48

tkelman reviewed Aug 31, 2016
View reviewed changes

This was referenced Sep 1, 2016

Removed confusing array of types in readcsv help #18308

Merged

Deprecate functions vectorized via @vectorize_(1|2)arg in favor of compact broadcast syntax #17302

Merged

tkelman reviewed Sep 1, 2016
View reviewed changes

kshyatt added 3 commits September 3, 2016 09:08

Moved so many docs out of HelpDB. More examples.

86f3f7d

Moved docstrings to deal with aliasing

07c2cd9

More wording improvements, few more doctests

b4c6f59

kshyatt force-pushed the ksh/docamputation branch from 269a924 to b4c6f59 Compare September 3, 2016 16:09

kshyatt merged commit 06c0ba6 into master Sep 3, 2016

kshyatt deleted the ksh/docamputation branch September 3, 2016 17:33

mfasi pushed a commit to mfasi/julia that referenced this pull request Sep 5, 2016

Add note about docstrings for aliases (JuliaLang#18157)

f117cc9

As mentioned in JuliaLang#18041 (comment) docstrings attached to aliases of functions should be avoided where possible.

tkelman added this to the 0.5.x milestone Sep 7, 2016

waldyrious mentioned this pull request Sep 7, 2016

Moving Docstrings #12703

Closed

nalimilan mentioned this pull request Jun 15, 2017

Remove order::Ordering keyword argument to sort* methods where possible #22388

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Moved so many docs out of HelpDB. More examples. #18041

Moved so many docs out of HelpDB. More examples. #18041

kshyatt commented Aug 15, 2016

tkelman Aug 16, 2016

kshyatt commented Aug 16, 2016

MichaelHatherly Aug 17, 2016

kshyatt Aug 18, 2016

MichaelHatherly Aug 19, 2016

tkelman Aug 19, 2016

MichaelHatherly Aug 19, 2016

kshyatt commented Aug 19, 2016

MichaelHatherly commented Aug 19, 2016

kshyatt commented Aug 19, 2016

MichaelHatherly commented Aug 19, 2016

kshyatt commented Aug 19, 2016

ViralBShah commented Aug 20, 2016 •

edited

Loading

tkelman commented Aug 20, 2016

MichaelHatherly commented Aug 20, 2016

MichaelHatherly Aug 20, 2016

kshyatt commented Aug 23, 2016

tkelman commented Aug 23, 2016

tkelman Aug 31, 2016

tkelman Sep 1, 2016

kshyatt commented Sep 3, 2016

tkelman commented Sep 3, 2016

kshyatt commented Sep 3, 2016

tkelman commented Sep 3, 2016

kshyatt commented Sep 3, 2016

Moved so many docs out of HelpDB. More examples. #18041

Moved so many docs out of HelpDB. More examples. #18041

Conversation

kshyatt commented Aug 15, 2016

Choose a reason for hiding this comment

kshyatt commented Aug 16, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kshyatt commented Aug 19, 2016

MichaelHatherly commented Aug 19, 2016

kshyatt commented Aug 19, 2016

MichaelHatherly commented Aug 19, 2016

kshyatt commented Aug 19, 2016

ViralBShah commented Aug 20, 2016 • edited Loading

tkelman commented Aug 20, 2016

MichaelHatherly commented Aug 20, 2016

Choose a reason for hiding this comment

kshyatt commented Aug 23, 2016

tkelman commented Aug 23, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kshyatt commented Sep 3, 2016

tkelman commented Sep 3, 2016

kshyatt commented Sep 3, 2016

tkelman commented Sep 3, 2016

kshyatt commented Sep 3, 2016

ViralBShah commented Aug 20, 2016 •

edited

Loading