Merge pull request #34424 from JuliaLang/kf/docrollup

Roll up stalled out doc PRs

Author: Keno

doc/src/manual/calling-c-and-fortran-code.md

@@ -75,7 +75,7 @@ julia> typeof(ans)
 Int32
 ```
 
-`clock` takes no arguments and returns an [`Int32`](@ref). One common gotcha is that a 1-tuple of
+`clock` takes no arguments and returns an [`Int32`](@ref). One common mistake is forgetting that a 1-tuple of
 argument types must be written with a trailing comma. For example, to call the `getenv` function
 to get a pointer to the value of an environment variable, one makes a call like this:
 
@@ -87,7 +87,7 @@ julia> unsafe_string(path)
 "/bin/bash"
 ```
 
-Note that the argument type tuple must be written as `(Cstring,)`, rather than `(Cstring)`. This
+Note that the argument type tuple must be written as `(Cstring,)`, not `(Cstring)`. This
 is because `(Cstring)` is just the expression `Cstring` surrounded by parentheses, rather than
 a 1-tuple containing `Cstring`:
 
@@ -101,7 +101,7 @@ julia> (Cstring,)
 
 In practice, especially when providing reusable functionality, one generally wraps [`ccall`](@ref)
 uses in Julia functions that set up arguments and then check for errors in whatever manner the
-C or Fortran function indicates them, propagating to the Julia caller as exceptions. This is especially
+C or Fortran function specifies. And if an error occurs it is thrown as a normal Julia exception. This is especially
 important since C and Fortran APIs are notoriously inconsistent about how they indicate error
 conditions. For example, the `getenv` C library function is wrapped in the following Julia function,
 which is a simplified version of the actual definition from [`env.jl`](https://github.com/JuliaLang/julia/blob/master/base/env.jl):
@@ -146,11 +146,11 @@ function gethostname()
 end
 ```
 
-This example first allocates an array of bytes, then calls the C library function `gethostname`
-to fill the array in with the hostname, takes a pointer to the hostname buffer, and converts the
+This example first allocates an array of bytes. It then calls the C library function `gethostname`
+to populate the array with the hostname. Finally, it takes a pointer to the hostname buffer, and converts the
 pointer to a Julia string, assuming that it is a NUL-terminated C string. It is common for C libraries
 to use this pattern of requiring the caller to allocate memory to be passed to the callee and
-filled in. Allocation of memory from Julia like this is generally accomplished by creating an
+populated. Allocation of memory from Julia like this is generally accomplished by creating an
 uninitialized array and passing a pointer to its data to the C function. This is why we don't
 use the `Cstring` type here: as the array is uninitialized, it could contain NUL bytes. Converting
 to a `Cstring` as part of the [`ccall`](@ref) checks for contained NUL bytes and could therefore
@@ -177,7 +177,7 @@ Julia function. The arguments to [`@cfunction`](@ref) are:
 
 !!! note
     Currently, only the platform-default C calling convention is supported. This means that
-    `@cfunction`-generated pointers cannot be used in calls where WINAPI expects `stdcall`
+    `@cfunction`-generated pointers cannot be used in calls where WINAPI expects a `stdcall`
     function on 32-bit Windows, but can be used on WIN64 (where `stdcall` is unified with the
     C calling convention).
 
@@ -193,8 +193,8 @@ each. `compare` is a callback function which takes pointers to two elements `a`
 an integer less/greater than zero if `a` should appear before/after `b` (or zero if any order
 is permitted).
 
-Now, suppose that we have a 1d array `A` of values in Julia that we want to sort
-using the `qsort` function (rather than Julia's built-in `sort` function). Before we worry about
+Now, suppose that we have a 1-d array `A` of values in Julia that we want to sort
+using the `qsort` function (rather than Julia's built-in `sort` function). Before we consider
 calling `qsort` and passing arguments, we need to write a comparison function:
 
 ```jldoctest mycompare
@@ -238,7 +238,7 @@ julia> A
   4.4
 ```
 
-As can be seen, `A` is changed to the sorted array `[-2.7, 1.3, 3.1, 4.4]`. Note that Julia
+As the example shows, the original Julia array `A` has now been sorted: `[-2.7, 1.3, 3.1, 4.4]`. Note that Julia
 [takes care of converting the array to a `Ptr{Cdouble}`](@ref automatic-type-conversion)), computing
 the size of the element type in bytes, and so on.
 
@@ -265,7 +265,7 @@ to the specified type. For example, the following call:
 ccall((:foo, "libfoo"), Cvoid, (Int32, Float64), x, y)
 ```
 
-will behave as if the following were written:
+will behave as if it were written like this:
 
 ```julia
 ccall((:foo, "libfoo"), Cvoid, (Int32, Float64),
@@ -349,7 +349,7 @@ same:
 
 On all systems we currently support, basic C/C++ value types may be translated to Julia types
 as follows. Every C type also has a corresponding Julia type with the same name, prefixed by C.
-This can help for writing portable code (and remembering that an `int` in C is not the same as
+This can help when writing portable code (and remembering that an `int` in C is not the same as
 an `Int` in Julia).
 
 
@@ -410,7 +410,7 @@ checks and is only meant to improve readability of the call.
 
 !!! warning
     For string arguments (`char*`) the Julia type should be `Cstring` (if NUL- terminated data is
-    expected) or either `Ptr{Cchar}` or `Ptr{UInt8}` otherwise (these two pointer types have the same
+    expected), or either `Ptr{Cchar}` or `Ptr{UInt8}` otherwise (these two pointer types have the same
     effect), as described above, not `String`. Similarly, for array arguments (`T[]` or `T*`), the
     Julia type should again be `Ptr{T}`, not `Vector{T}`.
 
@@ -419,19 +419,19 @@ checks and is only meant to improve readability of the call.
     `wint_t`) on all platforms.
 
 !!! warning
-    A return type of `Union{}` means the function will not return i.e. C++11 `[[noreturn]]` or C11
+    A return type of `Union{}` means the function will not return, i.e., C++11 `[[noreturn]]` or C11
     `_Noreturn` (e.g. `jl_throw` or `longjmp`). Do not use this for functions that return no value
     (`void`) but do return, use `Cvoid` instead.
 
 !!! note
     For `wchar_t*` arguments, the Julia type should be [`Cwstring`](@ref) (if the C routine expects a
-    NUL-terminated string) or `Ptr{Cwchar_t}` otherwise. Note also that UTF-8 string data in Julia is
+    NUL-terminated string), or `Ptr{Cwchar_t}` otherwise. Note also that UTF-8 string data in Julia is
     internally NUL-terminated, so it can be passed to C functions expecting NUL-terminated data without
     making a copy (but using the `Cwstring` type will cause an error to be thrown if the string itself
     contains NUL characters).
 
 !!! note
-    C functions that take an argument of the type `char**` can be called by using a `Ptr{Ptr{UInt8}}`
+    C functions that take an argument of type `char**` can be called by using a `Ptr{Ptr{UInt8}}`
     type within Julia. For example, C functions of the form:
 
     ```c
@@ -450,7 +450,7 @@ checks and is only meant to improve readability of the call.
     are provided as *hidden arguments*. Type and position of these arguments in the list are compiler
     specific, where compiler vendors usually default to using `Csize_t` as type and append the hidden
     arguments at the end of the argument list. While this behaviour is fixed for some compilers (GNU),
-    others *optionally* permit placing hidden arguments directly after the character argument (Intel,PGI).
+    others *optionally* permit placing hidden arguments directly after the character argument (Intel, PGI).
     For example, Fortran subroutines of the form
 
     ```fortran
@@ -479,7 +479,7 @@ checks and is only meant to improve readability of the call.
 
 ### Struct Type Correspondences
 
-Composite types, aka `struct` in C or `TYPE` in Fortran90 (or `STRUCTURE` / `RECORD` in some variants
+Composite types such as `struct` in C or `TYPE` in Fortran90 (or `STRUCTURE` / `RECORD` in some variants
 of F77), can be mirrored in Julia by creating a `struct` definition with the same
 field layout.
 
@@ -855,12 +855,12 @@ When passing data to a [`ccall`](@ref), it is best to avoid using the [`pointer`
 Instead define a convert method and pass the variables directly to the [`ccall`](@ref). [`ccall`](@ref)
 automatically arranges that all of its arguments will be preserved from garbage collection until
 the call returns. If a C API will store a reference to memory allocated by Julia, after the [`ccall`](@ref)
-returns, you must arrange that the object remains visible to the garbage collector. The suggested
-way to handle this is to make a global variable of type `Array{Ref,1}` to hold these values, until
+returns, you must ensure that the object remains visible to the garbage collector. The suggested
+way to do this is to make a global variable of type `Array{Ref,1}` to hold these values, until
 the C library notifies you that it is finished with them.
 
 Whenever you have created a pointer to Julia data, you must ensure the original data exists until
-you are done with using the pointer. Many methods in Julia such as [`unsafe_load`](@ref) and
+you have finished using the pointer. Many methods in Julia such as [`unsafe_load`](@ref) and
 [`String`](@ref) make copies of data instead of taking ownership of the buffer, so that it is
 safe to free (or alter) the original data without affecting Julia. A notable exception is
 [`unsafe_wrap`](@ref) which, for performance reasons, shares (or can be told to take ownership of) the
@@ -888,7 +888,8 @@ when wrapping libraries that contain many similar functions.
 A similar example can be constructed for [`@cfunction`](@ref).
 
 However, doing this will also be very slow and leak memory, so you should usually avoid this and instead keep
-reading.  The next section discusses how to use indirect calls to efficiently accomplish a similar effect.
+reading.
+The next section discusses how to use indirect calls to efficiently achieve a similar effect.
 
 ## Indirect Calls
 

doc/src/manual/conversion-and-promotion.md

@@ -93,8 +93,8 @@ ERROR: MethodError: Cannot `convert` an object of type String to an object of ty
 ```
 
 Some languages consider parsing strings as numbers or formatting numbers as strings to be conversions
-(many dynamic languages will even perform conversion for you automatically), however Julia does
-not: even though some strings can be parsed as numbers, most strings are not valid representations
+(many dynamic languages will even perform conversion for you automatically). This is not the case in Julia.
+Even though some strings can be parsed as numbers, most strings are not valid representations
 of numbers, and only a very limited subset of them are. Therefore in Julia the dedicated [`parse`](@ref)
 function must be used to perform this operation, making it more explicit.
 

doc/src/manual/documentation.md

@@ -3,10 +3,10 @@
 Julia enables package developers and users to document functions, types and other objects easily
 via a built-in documentation system since Julia 0.4.
 
-The basic syntax is simple: any string appearing at the top-level right before an object
-(function, macro, type or instance) will be interpreted as documenting it (these are called *docstrings*).
-Note that no blank lines or comments may intervene between a docstring and the documented object.
-Here is a basic example:
+The basic syntax is simple: any string appearing at the toplevel right before an object
+(function, macro, type or instance) will be interpreted as documenting it (these are called
+*docstrings*). Note that no blank lines or comments may intervene between a docstring and
+the documented object. Here is a basic example:
 
 ```julia
 "Tell whether there are too foo items in the array."
@@ -187,16 +187,16 @@ As in the example above, we recommend following some simple conventions when wri
    f(x, y) = ...
    ```
 
-   This makes it more clear where docstrings start and end.
+   This makes it clearer where docstrings start and end.
 9. Respect the line length limit used in the surrounding code.
 
    Docstrings are edited using the same tools as code. Therefore, the same conventions should apply.
-   It is advised to add line breaks after 92 characters.
+   It is recommended that lines are at most 92 characters wide.
 6. Provide information allowing custom types to implement the function in an
-   `# Implementation` section. These implementation details intended for developers
-   rather than users, explaining e.g. which functions should be overridden and which functions
-   automatically use appropriate fallbacks, are better kept separate from the main description of
-   the function's behavior.
+   `# Implementation` section. These implementation details are intended for developers
+   rather than users, explaining e.g. which functions should be overridden and which
+   functions automatically use appropriate fallbacks. Such details are best kept separate
+   from the main description of the function's behavior.
 
 ## Accessing Documentation
 
@@ -209,8 +209,9 @@ by typing `?` followed by the name of a function or macro, and pressing `Enter`.
 ?r""
 ```
 
-will bring up docs for the relevant function, macro or string macro respectively. In [Juno](http://junolab.org)
-using `Ctrl-J, Ctrl-D` will bring up documentation for the object under the cursor.
+will show documentation for the relevant function, macro or string macro respectively. In
+[Juno](http://junolab.org) using `Ctrl-J, Ctrl-D` will show the documentation for the object
+under the cursor.
 
 ## Functions & Methods
 
@@ -334,7 +335,9 @@ y = MyType("y")
 
 ## Syntax Guide
 
-A comprehensive overview of all documentable Julia syntax.
+This guide provides a comprehensive overview of how to attach documentation to all Julia syntax
+constructs for which providing documentation is possible.
+
 In the following examples `"..."` is used to illustrate an arbitrary docstring.
 
 ### `$` and `\` characters
@@ -520,8 +523,8 @@ the referenced value itself.
 sym
 ```
 
-Adds docstring `"..."` to the value associated with `sym`. Users should prefer documenting `sym`
-at its definition.
+Adds docstring `"..."` to the value associated with `sym`. However, it is preferred that
+`sym` is documented where it is defined.
 
 ### Multiple Objects
 
@@ -551,9 +554,9 @@ two functions are related, such as non-mutating and mutating versions `f` and `f
 @m expression
 ```
 
-Adds docstring `"..."` to expression generated by expanding `@m expression`. This allows for expressions
-decorated with `@inline`, `@noinline`, `@generated`, or any other macro to be documented in the
-same way as undecorated expressions.
+Adds docstring `"..."` to the expression generated by expanding `@m expression`. This allows
+for expressions decorated with `@inline`, `@noinline`, `@generated`, or any other macro to
+be documented in the same way as undecorated expressions.
 
 Macro authors should take note that only macros that generate a single expression will automatically
 support docstrings. If a macro returns a block containing multiple subexpressions then the subexpression

doc/src/manual/environment-variables.md

@@ -11,8 +11,8 @@ determined by evaluating `ENV["JULIA_EDITOR"]`.
 
 The environment variables that Julia uses generally start with `JULIA`. If
 [`InteractiveUtils.versioninfo`](@ref) is called with the keyword `verbose=true`, then the
-output will list defined environment variables relevant for Julia, including
-those for which `JULIA` appears in the name.
+output will list any defined environment variables relevant for Julia,
+including those which include `JULIA` in their names.
 
 !!! note
 
@@ -148,10 +148,10 @@ $(DEPOT_PATH[1])/logs/repl_history.jl
 
 ### `JULIA_PKGRESOLVE_ACCURACY`
 
-A positive `Int` that determines how much time the max-sum subroutine
-`MaxSum.maxsum()` of the package dependency resolver
-will devote to attempting satisfying constraints before giving up: this value is
-by default `1`, and larger values correspond to larger amounts of time.
+A positive `Int` that determines how much time the package dependency resolver's max-sum
+subroutine `MaxSum.maxsum()` will devote to attempting to satisfy constraints before giving
+up. This value's default is `1`, with higher values corresponding to longer amounts of
+time.
 
 Suppose the value of `$JULIA_PKGRESOLVE_ACCURACY` is `n`. Then
 

doc/src/manual/faq.md

@@ -141,9 +141,9 @@ When calling `change_value!(x)` in the above example, `y` is a newly created var
 to the value of `x`, i.e. `10`; then `y` is rebound to the constant `17`, while the variable
 `x` of the outer scope is left untouched.
 
-But here is a thing you should pay attention to: suppose `x` is bound to an object of type `Array`
+However, if `x` is bound to an object of type `Array`
 (or any other *mutable* type). From within the function, you cannot "unbind" `x` from this Array,
-but you can change its content. For example:
+but you *can* change its content. For example:
 
 ```jldoctest
 julia> x = [1,2,3]
@@ -334,8 +334,8 @@ unstable (generic function with 1 method)
 
 It returns either an `Int` or a [`Float64`](@ref) depending on the value of its argument.
 Since Julia can't predict the return type of this function at compile-time, any computation
-that uses it will have to guard against both types possibly occurring, making generation of
-fast machine code difficult.
+that uses it must be able to cope with values of both types, which makes it hard to produce
+fast machine code.
 
 ### [Why does Julia give a `DomainError` for certain seemingly-sensible operations?](@id faq-domain-errors)
 
@@ -770,8 +770,9 @@ generate efficient code when working with `Union{T, Nothing}` arguments or field
 To represent missing data in the statistical sense (`NA` in R or `NULL` in SQL), use the
 [`missing`](@ref) object. See the [`Missing Values`](@ref missing) section for more details.
 
-The empty tuple (`()`) is another form of nothingness. But, it should not really be thought of
-as nothing but rather a tuple of zero values.
+In some languages, the empty tuple (`()`) is considered the canonical
+form of nothingness. However, in julia it is best thought of as just
+a regular tuple that happens to contain zero values.
 
 The empty (or "bottom") type, written as `Union{}` (an empty union type), is a type with
 no values and no subtypes (except itself). You will generally not need to use this type.