Merge pull request #28396 from JuliaLang/ksh/docstrings

Doc Cstring and Cwstring

Author: kshyatt

base/c.jl

@@ -122,6 +122,31 @@ Equivalent to the native `wchar_t` c-type ([`Int32`](@ref)).
 """
 Cwchar_t
 
+"""
+    Cwstring
+
+A C-style string composed of the native wide character type
+[`Cwchar_t`](@ref)s. `Cwstring`s are NUL-terminated. For
+C-style strings composed of the native character
+type, see [`Cstring`](@ref). For more information
+about string interopability with C, see the
+[manual](@ref man-bits-types).
+
+"""
+Cwstring
+
+"""
+    Cstring
+
+A C-style string composed of the native character type
+[`Cchar`](@ref)s. `Cstring`s are NUL-terminated. For
+C-style strings composed of the native wide character
+type, see [`Cwstring`](@ref). For more information
+about string interopability with C, see the
+[manual](@ref man-bits-types).
+"""
+Cstring
+
 @static if ccall(:jl_get_UNAME, Any, ()) !== :NT
     const sizeof_mode_t = ccall(:jl_sizeof_mode_t, Cint, ())
     if sizeof_mode_t == 2
@@ -214,7 +239,7 @@ unsafe_convert(::Type{Cstring}, s::Symbol) = Cstring(unsafe_convert(Ptr{Cchar},
 
 Converts a string `s` to a NUL-terminated `Vector{Cwchar_t}`, suitable for passing to C
 functions expecting a `Ptr{Cwchar_t}`. The main advantage of using this over the implicit
-conversion provided by `Cwstring` is if the function is called multiple times with the
+conversion provided by [`Cwstring`](@ref) is if the function is called multiple times with the
 same argument.
 
 This is only available on Windows.
@@ -236,7 +261,7 @@ Convert string data between Unicode encodings. `src` is either a
 `String` or a `Vector{UIntXX}` of UTF-XX code units, where
 `XX` is 8, 16, or 32. `T` indicates the encoding of the return value:
 `String` to return a (UTF-8 encoded) `String` or `UIntXX`
-to return a `Vector{UIntXX}` of UTF-`XX` data.   (The alias `Cwchar_t`
+to return a `Vector{UIntXX}` of UTF-`XX` data. (The alias [`Cwchar_t`](@ref)
 can also be used as the integer type, for converting `wchar_t*` strings
 used by external C libraries.)
 
@@ -428,7 +453,7 @@ end
     reenable_sigint(f::Function)
 
 Re-enable Ctrl-C handler during execution of a function.
-Temporarily reverses the effect of `disable_sigint`.
+Temporarily reverses the effect of [`disable_sigint`](@ref).
 """
 function reenable_sigint(f::Function)
     sigatomic_end()

doc/src/base/c.md

@@ -24,6 +24,7 @@ Core.Ref
 Base.Cchar
 Base.Cuchar
 Base.Cshort
+Base.Cstring
 Base.Cushort
 Base.Cint
 Base.Cuint
@@ -37,6 +38,7 @@ Base.Csize_t
 Base.Cssize_t
 Base.Cptrdiff_t
 Base.Cwchar_t
+Base.Cwstring
 Base.Cfloat
 Base.Cdouble
 ```

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

@@ -287,7 +287,7 @@ First, a review of some relevant Julia type terminology:
 | `struct ...; end`             | `nothing`                                   | "Singleton" :: a Leaf Type or Struct with no fields.                                                                                                                                                                                                                        |
 | `(...)` or `tuple(...)`       | `(1, 2, 3)`                                 | "Tuple" :: an immutable data-structure similar to an anonymous struct type, or a constant array. Represented as either an array or a struct.                                                                                                                                |
 
-### Bits Types:
+### [Bits Types](@id man-bits-types)
 
 There are several special types to be aware of, as no other type can be defined to behave the
 same:
@@ -374,7 +374,7 @@ an `Int` in Julia).
 | `va_arg`                                                |                          |                      | Not supported                                                                                                  |
 | `...` (variadic function specification)                 |                          |                      | `T...` (where `T` is one of the above types, variadic functions of different argument types are not supported) |
 
-The `Cstring` type is essentially a synonym for `Ptr{UInt8}`, except the conversion to `Cstring`
+The [`Cstring`](@ref) type is essentially a synonym for `Ptr{UInt8}`, except the conversion to `Cstring`
 throws an error if the Julia string contains any embedded NUL characters (which would cause the
 string to be silently truncated if the C routine treats NUL as the terminator).  If you are passing
 a `char*` to a C routine that does not assume NUL termination (e.g. because you pass an explicit
@@ -413,7 +413,7 @@ checks and is only meant to improve readability of the call.
     (`void`) but do return, use `Cvoid` instead.
 
 !!! note
-    For `wchar_t*` arguments, the Julia type should be `Cwstring` (if the C routine expects a NUL-terminated
+    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 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