From 5edd47c0574762c3e4b44c8045b3263c4bbac9a4 Mon Sep 17 00:00:00 2001 From: Jeff Bezanson Date: Mon, 7 Sep 2015 18:57:06 -0400 Subject: [PATCH] fix `summarysize` docstring and some copy edits to CONTRIBUTING.md --- CONTRIBUTING.md | 6 +++--- base/interactiveutil.jl | 9 +++------ doc/stdlib/base.rst | 4 ++-- 3 files changed, 8 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0dd6410af95de..75c03a5ec63f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,10 +83,10 @@ or from Julia's root directory. Sometimes errors only show up in one of them, so if you're preparing a pull request it is nice if you've checked both formats before you submit. Existing docstrings now live primarily in `base/docs/helpdb.jl`. -It is a goal over time to move the docstrings inline to their respective method definition. -If you want to edit the body of a method docstring, you simply then need to run the `doc/genstdlib.jl` script to regenerate the restructured text files **after** you have already rebuilt Julia. +It is a goal over time to move the docstrings inline to their respective method definitions. +If you want to edit the body of a method docstring, run the `doc/genstdlib.jl` script to regenerate the restructured text files **after** you have already rebuilt Julia. If you want to edit an existing docstring signature, you **first** have to change the signature in the `doc/stdlib` `..function` or `..data` definition (not the auto-generated content) and *then* -edit the helpdb.jl or inline method docstrings. The existing signatures in the `doc/stdlib/*.rst` files are patterned matched to base docstrings and the new content overwrites the content in `doc/stdlib/`. +edit the helpdb.jl or inline method docstrings. The existing signatures in the `doc/stdlib/*.rst` files are pattern matched to base docstrings and the new content overwrites the content in `doc/stdlib/`. The signature definitions **must** be in sync or else the pattern match will fail and documentation will be lost in the result. To add entirely new methods to the `stdlib` documentation, first add the signature in the appropriate `rst/stdlib/*.rst` file before writing the docstring, rebuilding Julia, and re-running `doc/genstdlib.jl`. diff --git a/base/interactiveutil.jl b/base/interactiveutil.jl index 35631b21f5137..162b3261d12ae 100644 --- a/base/interactiveutil.jl +++ b/base/interactiveutil.jl @@ -468,13 +468,10 @@ whos(pat::Regex) = whos(STDOUT, current_module(), pat) ################################################################################# """ - Base.summarysize(obj, recurse) -> Int + Base.summarysize(obj; exclude=Union{Module,Function,DataType,TypeName}) -> Int -`summarysize` is an estimate of the size of the object as if all iterables were -allocated inline in general, this forms a conservative lower bound n the memory -"controlled" by the object if recurse is `true`, then simply reachable memory -should also be included, otherwise, only directly used memory should be included -you should never ignore recurse in cases where recursion is possible +Compute the amount of memory used by all unique objects reachable from the argument. +Keyword argument `exclude` specifies a type of objects to exclude from the traversal. """ summarysize(obj; exclude = Union{Module,Function,DataType,TypeName}) = summarysize(obj, ObjectIdDict(), exclude) diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 4a533d12eb1e5..dbdb83802015b 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -58,11 +58,11 @@ Getting Around The memory consumption estimate is an approximate lower bound on the size of the internal structure of the object. -.. function:: Base.summarysize(obj, recurse) -> Int +.. function:: Base.summarysize(obj; exclude=Union{Module,Function,DataType,TypeName}) -> Int .. Docstring generated from Julia source - ``summarysize`` is an estimate of the size of the object as if all iterables were allocated inline in general, this forms a conservative lower bound n the memory "controlled" by the object if recurse is ``true``\ , then simply reachable memory should also be included, otherwise, only directly used memory should be included you should never ignore recurse in cases where recursion is possible + Compute the amount of memory used by all unique objects reachable from the argument. Keyword argument ``exclude`` specifies a type of objects to exclude from the traversal. .. function:: edit(file::AbstractString, [line])