doc: update helpdb.jl

Author: nolta

doc/helpdb.jl

@@ -189,29 +189,49 @@
 
 ("All Objects","Base","isequal","isequal(x, y)
 
-   True if and only if \"x\" and \"y\" have the same contents. Loosely
-   speaking, this means \"x\" and \"y\" would look the same when
-   printed. This is the default comparison function used by hash
-   tables (\"Dict\"). New types with a notion of equality should
-   implement this function, except for numbers, which should implement
-   \"==\" instead. However, numeric types with special values might
-   need to implement \"isequal\" as well. For example, floating point
-   \"NaN\" values are not \"==\", but are all equivalent in the sense
-   of \"isequal\". Numbers of different types are considered unequal.
+   True if and only if \"x\" and \"y\" would cause a typical function
+   to behave the same. A \"typical\" function is one that uses only
+   intended interfaces, and does not unreasonably exploit
+   implementation details of its arguments. For example, floating-
+   point \"NaN\" values are \"isequal\" regardless of their sign bits,
+   since the sign of a \"NaN\" has no meaning in the vast majority of
+   cases (but can be discovered if you really want to).
+
+   One implication of this definition is that implementing \"isequal\"
+   for a new type encapsulates, to a large extent, what the true
+   abstraction presented by that type is. For example, a \"String\" is
+   a sequence of characters, so two strings are \"isequal\" if they
+   generate the same characters. Other concerns, such as encoding, are
+   not considered.
+
+   When calling \"isequal\", be aware that it cannot be all things to
+   all people. For example, if your use of strings *does* care about
+   encoding, you will have to perform a check like
+   \"typeof(x)==typeof(y) && isequal(x,y)\".
+
+   \"isequal\" is the default comparison function used by hash tables
+   (\"Dict\"). \"isequal(x,y)\" must imply \"hash(x)==hash(y)\".
+
+   New types with a notion of equality should implement this function,
+   except for numbers, which should implement \"==\" instead. However,
+   numeric types with special values like \"NaN\" might need to
+   implement \"isequal\" as well. Numbers of different types are
+   considered unequal.
+
    Mutable containers should generally implement \"isequal\" by
    calling \"isequal\" recursively on all contents.
 
 "),
 
 ("All Objects","Base","isless","isless(x, y)
 
-   Test whether \"x\" is less than \"y\". Provides a total order
-   consistent with \"isequal\". Values that are normally unordered,
-   such as \"NaN\", are ordered in an arbitrary but consistent
-   fashion. This is the default comparison used by \"sort\". Non-
-   numeric types that can be ordered should implement this function.
-   Numeric types only need to implement it if they have special values
-   such as \"NaN\".
+   Test whether \"x\" is less than \"y\", according to a canonical
+   total order. Values that are normally unordered, such as \"NaN\",
+   are ordered in an arbitrary but consistent fashion. This is the
+   default comparison used by \"sort\". Non-numeric types with a
+   canonical total order should implement this function. Numeric types
+   only need to implement it if they have special values such as
+   \"NaN\".
 
 "),
 
@@ -2551,10 +2571,17 @@
 
 "),
 
-("Text I/O","Base","writedlm","writedlm(filename, array, delim::Char)
+("Text I/O","Base","writedlm","writedlm(f, A, delim='t')
+
+   Write \"A\" (either an array type or an iterable collection of
+   iterable rows) as text to \"f\" (either a filename string or an
+   \"IO\" stream) using the given delimeter \"delim\" (which defaults
+   to tab, but can be any printable Julia object, typically a \"Char\"
+   or \"String\").
 
-   Write an array to a text file using the given delimeter (defaults
-   to comma).
+   For example, two vectors \"x\" and \"y\" of the same length can be
+   written as two columns of tab-delimited text to \"f\" by either
+   \"writedlm(f, [x y])\" or by \"writedlm(f, zip(x, y))\".
 
 "),
 
@@ -2564,7 +2591,7 @@
 
 "),
 
-("Text I/O","Base","writecsv","writecsv(filename, array)
+("Text I/O","Base","writecsv","writecsv(filename, A)
 
    Equivalent to \"writedlm\" with \"delim\" set to comma.
 
@@ -3093,7 +3120,10 @@ popdisplay(d::Display)
 ("Mathematical Operators","Base","<","<(x, y)
 
    Less-than comparison operator. New numeric types should implement
-   this function for two arguments of the new type.
+   this function for two arguments of the new type. Because of the
+   behavior of floating-point NaN values, \"<\" implements a partial
+   order. Types with a canonical partial order should implement \"<\",
+   and types with a canonical total order should implement \"isless\".
 
 "),
 
@@ -3155,8 +3185,9 @@ popdisplay(d::Display)
 
 ("Mathematical Operators","Base","cmp","cmp(x, y)
 
-   Return -1, 0, or 1 depending on whether \"x<y\", \"x==y\", or
-   \"x>y\", respectively.
+   Return -1, 0, or 1 depending on whether \"x\" is less than, equal
+   to, or greater than \"y\", respectively. Uses the total order
+   implemented by \"isless\".
 
 "),
 
@@ -3647,9 +3678,9 @@ popdisplay(d::Display)
 
 "),
 
-("Mathematical Functions","Base","frexp","frexp(val, exp)
+("Mathematical Functions","Base","frexp","frexp(val)
 
-   Return a number \"x\" such that it has a magnitude in the interval
+   Return \"(x,exp)\" such that \"x\" has a magnitude in the interval
    \"[1/2, 1)\" or 0, and val = x \\times 2^{exp}.
 
 "),
@@ -8157,7 +8188,8 @@ popdisplay(d::Display)
 
 ("Linear Algebra","Base","dot","dot(x, y)
 
-   Compute the dot product
+   Compute the dot product. For complex vectors the first vector is
+   conjugated.
 
 "),
 
@@ -8917,12 +8949,23 @@ popdisplay(d::Display)
 
 "),
 
-("BLAS Functions","Base","dot","dot(n, X, incx, Y, incy)
+("BLAS Functions","Base.LinAlg.BLAS","dot","dot(n, X, incx, Y, incy)
 
    Dot product of two vectors consisting of \"n\" elements of array
    \"X\" with stride \"incx\" and \"n\" elements of array \"Y\" with
-   stride \"incy\".  There are no \"dot\" methods for \"Complex\"
-   arrays.
+   stride \"incy\".
+
+"),
+
+("BLAS Functions","Base.LinAlg.BLAS","dotu","dotu(n, X, incx, Y, incy)
+
+   Dot function for two complex vectors.
+
+"),
+
+("BLAS Functions","Base.LinAlg.BLAS","dotc","dotc(n, X, incx, U, incy)
+
+   Dot function for two complex vectors conjugating the first vector.
 
 "),