Skip to content

Commit

Permalink
[doc] Add @id for doc title - Part 2 (base and devdoc) (JuliaLang#43017)
Browse files Browse the repository at this point in the history
* [doc] add `@id base-multimedia`

* [doc] add `@id base-keywords`

* [doc] add `@id base-big`

* [doc] add `@id dev-debug`

* [doc] add `@id dev-func-call`

* [doc] add `@id dev-stdio-libuv`

* [doc] add `@id dev-sysimg-build`

* [doc] add `@id dev-locks`

* [doc] add `@id dev-stdio-ios-c`
  • Loading branch information
inkydragon committed Nov 9, 2021
1 parent 7e85914 commit 13afd74
Show file tree
Hide file tree
Showing 14 changed files with 22 additions and 21 deletions.
2 changes: 1 addition & 1 deletion doc/src/base/base.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ ans
Base.active_project
```

## Keywords
## [Keywords](@id base-keywords)

This is the list of reserved keywords in Julia:
`baremodule`, `begin`, `break`, `catch`, `const`, `continue`, `do`,
Expand Down
2 changes: 1 addition & 1 deletion doc/src/base/io-network.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Base.eachline
Base.displaysize
```

## Multimedia I/O
## [Multimedia I/O](@id base-multimedia)

Just as text output is performed by [`print`](@ref) and user-defined types can indicate their textual
representation by overloading [`show`](@ref), Julia provides a standardized mechanism for rich multimedia
Expand Down
2 changes: 1 addition & 1 deletion doc/src/base/numbers.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ Base.@int128_str
Base.@uint128_str
```

## BigFloats and BigInts
## [BigFloats and BigInts](@id base-big)

The [`BigFloat`](@ref) and [`BigInt`](@ref) types implements
arbitrary-precision floating point and integer arithmetic, respectively. For
Expand Down
3 changes: 2 additions & 1 deletion doc/src/devdocs/ast.md
Original file line number Diff line number Diff line change
Expand Up @@ -594,7 +594,8 @@ A unique'd container describing the shared metadata for a single method.

### MethodInstance

A unique'd container describing a single callable signature for a Method. See especially [Proper maintenance and care of multi-threading locks](@ref)
A unique'd container describing a single callable signature for a Method.
See especially [Proper maintenance and care of multi-threading locks](@ref dev-locks)
for important details on how to modify these fields safely.

* `specTypes`
Expand Down
2 changes: 1 addition & 1 deletion doc/src/devdocs/debuggingtips.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# gdb debugging tips
# [gdb debugging tips](@id dev-debug)

## Displaying Julia variables

Expand Down
2 changes: 1 addition & 1 deletion doc/src/devdocs/functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ share the same `Complex` type name object.
All objects in Julia are potentially callable, because every object has a type, which in turn
has a `TypeName`.

## Function calls
## [Function calls](@id dev-func-call)

Given the call `f(x,y)`, the following steps are performed: first, the method table to use is
accessed as `typeof(f).name.mt`. Second, an argument tuple type is formed, `Tuple{typeof(f), typeof(x), typeof(y)}`.
Expand Down
10 changes: 5 additions & 5 deletions doc/src/devdocs/init.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ which loads a few libraries, eventually calling [`repl_entrypoint()` in `src/jla

`repl_entrypoint()` calls [`libsupport_init()`](https://github.com/JuliaLang/julia/blob/master/src/support/libsupportinit.c)
to set the C library locale and to initialize the "ios" library (see [`ios_init_stdstreams()`](https://github.com/JuliaLang/julia/blob/master/src/support/ios.c)
and [Legacy `ios.c` library](@ref)).
and [Legacy `ios.c` library](@ref dev-stdio-ios-c)).

Next [`jl_parse_opts()`](https://github.com/JuliaLang/julia/blob/master/src/jloptions.c) is called to process
command line options. Note that `jl_parse_opts()` only deals with options that affect code generation
Expand All @@ -29,7 +29,7 @@ by `main()` and calls [`_julia_init()` in `init.c`](https://github.com/JuliaLang
to zero the signal handler mask.

[`jl_resolve_sysimg_location()`](https://github.com/JuliaLang/julia/blob/master/src/init.c) searches
configured paths for the base system image. See [Building the Julia system image](@ref).
configured paths for the base system image. See [Building the Julia system image](@ref dev-sysimg-build).

[`jl_gc_init()`](https://github.com/JuliaLang/julia/blob/master/src/gc.c) sets up allocation pools
and lists for weak refs, preserved values and finalization.
Expand Down Expand Up @@ -130,14 +130,14 @@ and `main()` calls `repl_entrypoint(argc, (char**)argv)`.
!!! sidebar "sysimg"
If there is a sysimg file, it contains a pre-cooked image of the `Core` and `Main` modules (and
whatever else is created by `boot.jl`). See [Building the Julia system image](@ref).
whatever else is created by `boot.jl`). See [Building the Julia system image](@ref dev-sysimg-build).
[`jl_restore_system_image()`](https://github.com/JuliaLang/julia/blob/master/src/staticdata.c) deserializes
the saved sysimg into the current Julia runtime environment and initialization continues after
`jl_init_box_caches()` below...
Note: [`jl_restore_system_image()` (and `staticdata.c` in general)](https://github.com/JuliaLang/julia/blob/master/src/staticdata.c)
uses the [Legacy `ios.c` library](@ref).
uses the [Legacy `ios.c` library](@ref dev-stdio-ios-c).
## `repl_entrypoint()`
Expand Down Expand Up @@ -174,7 +174,7 @@ and [`Base.print()`](@ref) before arriving at [`write(s::IO, a::Array{T}) where
which does `ccall(jl_uv_write())`.
[`jl_uv_write()`](https://github.com/JuliaLang/julia/blob/master/src/jl_uv.c) calls `uv_write()`
to write "Hello World!" to `JL_STDOUT`. See [Libuv wrappers for stdio](@ref).:
to write "Hello World!" to `JL_STDOUT`. See [Libuv wrappers for stdio](@ref dev-stdio-libuv).:
```
Hello World!
Expand Down
2 changes: 1 addition & 1 deletion doc/src/devdocs/locks.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Proper maintenance and care of multi-threading locks
# [Proper maintenance and care of multi-threading locks](@id dev-locks)

The following strategies are used to ensure that the code is dead-lock free (generally by addressing
the 4th Coffman condition: circular wait).
Expand Down
4 changes: 2 additions & 2 deletions doc/src/devdocs/stdio.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# printf() and stdio in the Julia runtime

## Libuv wrappers for stdio
## [Libuv wrappers for stdio](@id dev-stdio-libuv)

`julia.h` defines [libuv](http:https://docs.libuv.org) wrappers for the `stdio.h` streams:

Expand Down Expand Up @@ -74,7 +74,7 @@ In `jl_uv.c` the `jl_uv_puts()` function checks its `uv_stream_t* stream` argume
This allows for uniform use of `jl_printf()` throughout the runtime regardless of whether or not
any particular piece of code is reachable before initialization is complete.

## Legacy `ios.c` library
## [Legacy `ios.c` library](@id dev-stdio-ios-c)

The `src/support/ios.c` library is inherited from [femtolisp](https://github.com/JeffBezanson/femtolisp).
It provides cross-platform buffered file IO and in-memory temporary buffers.
Expand Down
2 changes: 1 addition & 1 deletion doc/src/devdocs/sysimg.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# System Image Building

## Building the Julia system image
## [Building the Julia system image](@id dev-sysimg-build)

Julia ships with a preparsed system image containing the contents of the `Base` module, named
`sys.ji`. This file is also precompiled into a shared library called `sys.{so,dll,dylib}` on
Expand Down
4 changes: 2 additions & 2 deletions doc/src/devdocs/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ f3(A::Array{T}) where {T<:Any} = 3
f4(A::Array{Any}) = 4
```

The signature - as described in [Function calls](@ref) - of `f3` is a `UnionAll` type wrapping a tuple type: `Tuple{typeof(f3), Array{T}} where T`.
The signature - as described in [Function calls](@ref dev-func-call) - of `f3` is a `UnionAll` type wrapping a tuple type: `Tuple{typeof(f3), Array{T}} where T`.
All but `f4` can be called with `a = [1,2]`; all but `f2` can be called with `b = Any[1,2]`.

Let's look at these types a little more closely:
Expand Down Expand Up @@ -478,7 +478,7 @@ We have not yet worked out a complete algorithm for this.
Most operations for dealing with types are found in the files `jltypes.c` and `subtype.c`.
A good way to start is to watch subtyping in action.
Build Julia with `make debug` and fire up Julia within a debugger.
[gdb debugging tips](@ref) has some tips which may be useful.
[gdb debugging tips](@ref dev-debug) has some tips which may be useful.

Because the subtyping code is used heavily in the REPL itself -- and hence breakpoints in this
code get triggered often -- it will be easiest if you make the following definition:
Expand Down
2 changes: 1 addition & 1 deletion doc/src/manual/functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ Argument-type declarations **normally have no impact on performance**: regardles
* **Correctness:** Type declarations can be useful if your function only returns correct results for certain argument types. For example, if we omitted argument types and wrote `fib(n) = n ≤ 2 ? one(n) : fib(n-1) + fib(n-2)`, then `fib(1.5)` would silently give us the nonsensical answer `1.0`.
* **Clarity:** Type declarations can serve as a form of documentation about the expected arguments.

However, it is a **common mistake to overly restrict the argument types**, which can unnecessarily limit the applicability of the function and prevent it from being re-used in circumstances you did not anticipate. For example, the `fib(n::Integer)` function above works equally well for `Int` arguments (machine integers) and `BigInt` arbitrary-precision integers (see [BigFloats and BigInts](@ref)), which is especially useful because Fibonacci numbers grow exponentially rapidly and will quickly overflow any fixed-precision type like `Int` (see [Overflow behavior](@ref)). If we had declared our function as `fib(n::Int)`, however, the application to `BigInt` would have been prevented for no reason. In general, you should use the most general applicable abstract types for arguments, and **when in doubt, omit the argument types**. You can always add argument-type specifications later if they become necessary, and you don't sacrifice performance or functionality by omitting them.
However, it is a **common mistake to overly restrict the argument types**, which can unnecessarily limit the applicability of the function and prevent it from being re-used in circumstances you did not anticipate. For example, the `fib(n::Integer)` function above works equally well for `Int` arguments (machine integers) and `BigInt` arbitrary-precision integers (see [BigFloats and BigInts](@ref base-big)), which is especially useful because Fibonacci numbers grow exponentially rapidly and will quickly overflow any fixed-precision type like `Int` (see [Overflow behavior](@ref)). If we had declared our function as `fib(n::Int)`, however, the application to `BigInt` would have been prevented for no reason. In general, you should use the most general applicable abstract types for arguments, and **when in doubt, omit the argument types**. You can always add argument-type specifications later if they become necessary, and you don't sacrifice performance or functionality by omitting them.

## The `return` Keyword

Expand Down
4 changes: 2 additions & 2 deletions doc/src/manual/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -1386,7 +1386,7 @@ REPL and other interactive environments, and also a more compact single-line for
[`print`](@ref) or for displaying the object as part of another object (e.g. in an array). Although
by default the `show(io, z)` function is called in both cases, you can define a *different* multi-line
format for displaying an object by overloading a three-argument form of `show` that takes the
`text/plain` MIME type as its second argument (see [Multimedia I/O](@ref)), for example:
`text/plain` MIME type as its second argument (see [Multimedia I/O](@ref base-multimedia)), for example:

```jldoctest polartype
julia> Base.show(io::IO, ::MIME"text/plain", z::Polar{T}) where{T} =
Expand All @@ -1409,7 +1409,7 @@ julia> [Polar(3, 4.0), Polar(4.0,5.3)]
where the single-line `show(io, z)` form is still used for an array of `Polar` values. Technically,
the REPL calls `display(z)` to display the result of executing a line, which defaults to `show(stdout, MIME("text/plain"), z)`,
which in turn defaults to `show(stdout, z)`, but you should *not* define new [`display`](@ref)
methods unless you are defining a new multimedia display handler (see [Multimedia I/O](@ref)).
methods unless you are defining a new multimedia display handler (see [Multimedia I/O](@ref base-multimedia)).

Moreover, you can also define `show` methods for other MIME types in order to enable richer display
(HTML, images, etcetera) of objects in environments that support this (e.g. IJulia). For example,
Expand Down
2 changes: 1 addition & 1 deletion doc/src/manual/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ julia> y = ___
ERROR: syntax: all-underscore identifier used as rvalue
```

The only explicitly disallowed names for variables are the names of the built-in [Keywords](@ref):
The only explicitly disallowed names for variables are the names of the built-in [Keywords](@ref base-keywords):

```julia-repl
julia> else = false
Expand Down

0 comments on commit 13afd74

Please sign in to comment.