`float`, `real`, `complex`: impove docs, move docs inline, and add doctest examples #19166

Tetralux · 2016-10-31T13:41:45Z

Fixes #18596 and #19113.

This PR:

adds documentation to these functions for when passing a Type, which was absent before.
- and jldoctest examples
moves the docs for float and complex inline from base/docs/helpdb/Base.jl into base/float.jl and base/complex.jl--where the functions are defined--respectively.

N.B: I haven't been able to verify that the doctests actually work...

$ make -C doc doctest
make: Entering directory '/home/dwight/julia/doc'
PATH=":/usr/local/bin:/usr/bin:/cygdrive/c/Users/dwight/cmder_mini/vendor/conemu-maximus5/ConEmu/Scripts:/cygdrive/c/Users/dwight/cmder_mini/vendor/conemu-maximus5:/cygdrive/c/Users/dwight/cmder_mini/vendor/conemu-maximus5/ConEmu:/cygdrive/c/ProgramData/Oracle/Java/javapath:/cygdrive/c/WINDOWS/system32:/cygdrive/c/WINDOWS:/cygdrive/c/WINDOWS/System32/Wbem:/cygdrive/c/WINDOWS/System32/WindowsPowerShell/v1.0:/cygdrive/c/Program Files/Microsoft SQL Server/110/Tools/Binn:/cygdrive/c/Program Files (x86)/Microsoft SDKs/TypeScript/1.0:/cygdrive/c/Program Files/Microsoft SQL Server/120/Tools/Binn:/cygdrive/c/Program Files/WIDCOMM/Bluetooth Software:/cygdrive/c/Program Files/WIDCOMM/Bluetooth Software/syswow64:/cygdrive/c/Program Files/Sublime Text 3:/cygdrive/c/Program Files (x86)/Windows Kits/8.1/Windows Performance Toolkit:/cygdrive/c/Program Files (x86)/Microsoft SDKs/F#/3.1/Framework/v4.0:/cygdrive/c/Program Files/Boo/bin:/cygdrive/c/clojure-1.6.0:/cygdrive/c/Program Files (x86)/IronPython 2.7:/cygdrive/c/Python27:/cygdrive/c/Program Files (x86)/scala/bin:/cygdrive/c/Program Files (x86)/NVIDIA Corporation/PhysX/Common:/cygdrive/c/Program Files/TortoiseHg:/cygdrive/c/Program Files (x86)/erl7.0/bin:/cygdrive/c/Program Files (x86)/Elixir/bin:/cygdrive/c/Program Files/Microsoft/Web Platform Installer:/cygdrive/c/WINDOWS/System32/WindowsPowerShell/v1.0:/cygdrive/c/Perl/perl/bin:/cygdrive/c/Program Files/nodejs:/cygdrive/c/Go/bin:/cygdrive/c/D/dmd2/windows/bin:/cygdrive/c/Program Files/Mercurial:/cygdrive/c/Program Files/Git/cmd:/cygdrive/c/WINDOWS/system32:/cygdrive/c/WINDOWS:/cygdrive/c/WINDOWS/System32/Wbem:/cygdrive/c/Program Files (x86)/Vim/vim80:/cygdrive/c/Users/dwight/.cargo/bin:/cygdrive/c/Users/dwight/bin:/cygdrive/c/Users/dwight/AppData/Local/scoop/shims:/cygdrive/c/Users/dwight/.symlink:/cygdrive/c/Users/dwight/AppData/Local/atom/bin:/cygdrive/c/Users/dwight/Dropbox/Projects/Go/bin:/cygdrive/c/Users/dwight/AppData/Roaming/npm:/cygdrive/c/Users/dwight/AppData/Local/Microsoft/WindowsApps:/cygdrive/c/Nim/dist/mingw:/cygdrive/c/Nim/dist/mingw/bin:/cygdrive/c/Nim/bin:/cygdrive/c/Nim/dist/babel" . ./../deps/scratch/julia-env/bin/activate && sphinx-build -b doctest -d ./_build/doctrees   /home/dwight/julia/doc ./_build/doctest
Running Sphinx v1.4.5
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [doctest]: targets for 87 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
running tests...

Document: manual/interfaces
---------------------------

Exception occurred:
  File "/usr/lib/python2.7/subprocess.py", line 1335, in _execute_child
    raise child_exception
OSError: [Errno 2] No such file or directory
The full traceback has been saved in /tmp/sphinx-err-30n_ir.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [Makefile:176: doctest] Error 1
make: Leaving directory '/home/dwight/julia/doc'

stevengj · 2016-10-31T17:46:34Z

base/complex.jl

-real{T<:Real}(::Type{T}) = T
-real{T<:Real}(::Type{Complex{T}}) = T
+"""
+ real{R<:Real}(::Type{R})


Should be more like:

real(T::Type) Given a numeric type `T`, return the corresponding `Real` type. For example, this returns `R` for `T = Complex{R}`. Equivalent to `typeof(real(zero(T)))`.

In fact, we should probably define a fallback method real(T::Type) = typeof(real(zero(T))).

Do you think that a similar fallback should be defined for complex and/or float as well?

float(T::Type) = typeof(float(zero(T))) complex(T::Type) = typeof(complex(zero(T)))

stevengj · 2016-10-31T17:49:43Z

base/complex.jl

+
+Convert real numbers or arrays to complex. `i` defaults to zero.
+
+ complex{R<:Real}(::Type{R})


Should be a separate docstring.

stevengj · 2016-10-31T17:51:07Z

base/complex.jl

+Gets an appropriate type that can represent a value of type `R` as a real number.
+For `R <: Complex{T}`, this function is equivalent to `real(T)`.
+
+```jldoctest


This seems like an excessive number of examples for such a simple function.

stevengj · 2016-11-01T17:27:50Z

base/complex.jl


-complex{T<:Real}(::Type{T}) = Complex{T}
-complex{T<:Real}(::Type{Complex{T}}) = Complex{T}
+Gets the type that represents the real part of a value of type `N`.


Gets -> returns.

As a stylistic matter, we usually don't use the letter N for type arguments. Usually it is T or R,S. That's why I suggested T and Complex{R}.

stevengj · 2016-11-01T17:28:28Z

base/complex.jl

-complex{T<:Real}(::Type{T}) = Complex{T}
-complex{T<:Real}(::Type{Complex{T}}) = Complex{T}
+Gets the type that represents the real part of a value of type `N`.
+e.g: for `N <: Complex{T}`, returns `T`.


Since Compex{T} is concrete, <: is superfluous. Just use N == Complex{T}.

stevengj · 2016-11-01T17:30:20Z

base/complex.jl

+
+julia> complex(Int)
+Complex{Int64}
+```


Two examples should suffice.

stevengj · 2016-11-01T17:31:38Z

base/float.jl

+ float(N::Type)
+
+Gets an appropriate type to represent a value of type `N` as a floating point value.
+For `N <: Complex{T}`, this function is equivalent to `float(T)`.


The second sentence is wrong, and in any case can probably be removed.

stevengj · 2016-11-01T17:32:00Z

base/float.jl

+Float64
+
+julia> float(Float16)
+Float16


Two examples, say Int, and Complex{Int}, should suffice here.

tkelman · 2016-11-04T21:37:07Z

base/complex.jl

+"""
+real(N::Type) = typeof(real(zero(N)))
+real{R<:Real}(::Type{R}) = R
+real{R<:Real}(::Type{Complex{R}}) = R


the code should also keep the existing type parameter naming convention

Dang it - missed this one!

stevengj · 2016-11-05T00:50:24Z

LGTM.

Tetralux · 2016-11-05T04:38:45Z

Travis failure seems unrelated.
Otherwise, unless there's anything else, I think this is RTM.

tkelman · 2016-11-05T14:04:46Z

should obviously be squashed (at merge time if necessary)

Tetralux · 2016-11-05T14:26:47Z

Squash complete.

stevengj · 2016-11-05T18:14:46Z

(No need to manually squash: the github merge button can do the squash for you.)

…iaLang#19166)

Tetralux force-pushed the h5/generictypefuncdocs branch from a560d51 to 0663c7b Compare October 31, 2016 14:30

StefanKarpinski approved these changes Oct 31, 2016

View reviewed changes

stevengj reviewed Oct 31, 2016

View reviewed changes

Tetralux changed the title ~~float, real, complex: impove docs, move docs inline, and add doctest examples~~ WIP: float, real, complex: impove docs, move docs inline, and add doctest examples Oct 31, 2016

stevengj reviewed Nov 1, 2016

View reviewed changes

base/complex.jl

julia> complex(Int)

Complex{Int64}

```

Copy link

Member

stevengj Nov 1, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two examples should suffice.

stevengj reviewed Nov 1, 2016

View reviewed changes

base/float.jl

Float64

julia> float(Float16)

Float16

Copy link

Member

stevengj Nov 1, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two examples, say Int, and Complex{Int}, should suffice here.

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

Tetralux force-pushed the h5/generictypefuncdocs branch 2 times, most recently from 251cb21 to 0b20e1b Compare November 4, 2016 13:53

tkelman reviewed Nov 4, 2016

View reviewed changes

Tetralux changed the title ~~WIP: float, real, complex: impove docs, move docs inline, and add doctest examples~~ float, real, complex: impove docs, move docs inline, and add doctest examples Nov 5, 2016

stevengj closed this Nov 5, 2016

stevengj reopened this Nov 5, 2016

Improve docs for float, real, complex and move docs inline

60a249e

Tetralux force-pushed the h5/generictypefuncdocs branch from 2374831 to 60a249e Compare November 5, 2016 14:26

stevengj merged commit 4b491df into JuliaLang:master Nov 5, 2016

Tetralux mentioned this pull request Nov 6, 2016

float(::Type) and real(::Type) are not documented #19113

Closed

Tetralux deleted the h5/generictypefuncdocs branch November 18, 2016 14:48

fcard pushed a commit to fcard/julia that referenced this pull request Feb 28, 2017

Improve docs for float, real, complex and move docs inline (Jul…

292ee05

…iaLang#19166)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`float`, `real`, `complex`: impove docs, move docs inline, and add doctest examples #19166

`float`, `real`, `complex`: impove docs, move docs inline, and add doctest examples #19166

Tetralux commented Oct 31, 2016

stevengj Oct 31, 2016 •

edited

Loading

stevengj Oct 31, 2016 •

edited

Loading

Tetralux Nov 1, 2016

stevengj Oct 31, 2016

stevengj Oct 31, 2016

stevengj Nov 1, 2016

stevengj Nov 1, 2016

stevengj Nov 1, 2016

stevengj Nov 1, 2016

stevengj Nov 1, 2016

stevengj Nov 1, 2016

tkelman Nov 4, 2016

Tetralux Nov 4, 2016

stevengj commented Nov 5, 2016

Tetralux commented Nov 5, 2016

tkelman commented Nov 5, 2016

Tetralux commented Nov 5, 2016

stevengj commented Nov 5, 2016


		Convert real numbers or arrays to complex. `i` defaults to zero.

		complex{R<:Real}(::Type{R})

float, real, complex: impove docs, move docs inline, and add doctest examples #19166

float, real, complex: impove docs, move docs inline, and add doctest examples #19166

Conversation

Tetralux commented Oct 31, 2016

stevengj Oct 31, 2016 • edited Loading

Choose a reason for hiding this comment

stevengj Oct 31, 2016 • edited Loading

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevengj commented Nov 5, 2016

Tetralux commented Nov 5, 2016

tkelman commented Nov 5, 2016

Tetralux commented Nov 5, 2016

stevengj commented Nov 5, 2016

`float`, `real`, `complex`: impove docs, move docs inline, and add doctest examples #19166

`float`, `real`, `complex`: impove docs, move docs inline, and add doctest examples #19166

stevengj Oct 31, 2016 •

edited

Loading

stevengj Oct 31, 2016 •

edited

Loading