Skip to content

Doc Guidelines for Unstable APIs #49503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Tokazama wants to merge 3 commits into from
Closed

Doc Guidelines for Unstable APIs #49503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a28565c
Guidelines for documenting usntable contributions (#49296)
Tokazama Apr 10, 2023
0efee90
Merge branch 'JuliaLang:master' into doc-guidelines
Tokazama Apr 25, 2023
2bdbdf4
Apply admonition to undocumented reflections.jl
Tokazama Apr 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ If you are already familiar with Julia itself, this blog post by Katharine Hyatt

* Review discussions on the [Julia Discourse forum](https://discourse.julialang.org).

* Review [Writing Documentation](https://github.com/JuliaLang/julia/blob/master/doc/src/manual/documentation.md#writing-documentation).

* For more detailed tips, read the [submission guide](https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#submitting-contributions) below.

* Relax and have fun!
Expand Down Expand Up @@ -181,6 +183,15 @@ At the moment, this should always be done with the following `compat` admonition
This method was added in Julia 1.X.
```

#### Documenting unstable APIs

Some contributions are intended primarily for internal use or may be part of an API that is still in development. In addition to appropriate documentation, relevant code should be clearly annotated as unstable as follows:

```
!!! danger "Unstable"
This method is unstable and subject to change without notice.
```

### Contributing to core functionality or base libraries

*By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).*
Expand Down
40 changes: 40 additions & 0 deletions base/reflection.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,6 +435,10 @@ located at `(dt.layout + sizeof(DataTypeLayout))`.
Can be called on any `isconcretetype`.

See also [`fieldoffset`](@ref).

!!! danger "Unstable"
This method is unstable and subject to change without notice.

"""
function datatype_fielddesc_type(dt::DataType)
@_foldable_meta
Expand Down Expand Up @@ -629,6 +633,9 @@ Determine whether type `T` is mutation free in the sense that no mutable memory
is reachable from this type (either in the type itself) or through any fields.
Note that the type itself need not be immutable. For example, an empty mutable
type is `ismutabletype`, but also `ismutationfree`.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function ismutationfree(@nospecialize(t))
t = unwrap_unionall(t)
Expand All @@ -648,6 +655,9 @@ datatype_isidentityfree(dt::DataType) = (@_total_meta; (dt.flags & 0x0200) == 0x

Determine whether type `T` is identity free in the sense that this type or any
reachable through its fields has non-content-based identity.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function isidentityfree(@nospecialize(t))
t = unwrap_unionall(t)
Expand Down Expand Up @@ -800,6 +810,9 @@ fieldtype
Get the index of a named field, throwing an error if the field does not exist (when err==true)
or returning 0 (when err==false).

!!! danger "Unstable"
This method is unstable and subject to change without notice.

# Examples
```jldoctest
julia> struct Foo
Expand Down Expand Up @@ -1128,6 +1141,9 @@ end
specializations(m::Method) → itr

Return an iterator `itr` of all compiler-generated specializations of `m`.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
specializations(m::Method) = MethodSpecializations(isdefined(m, :specializations) ? m.specializations : nothing)
function iterate(specs::MethodSpecializations)
Expand Down Expand Up @@ -1228,6 +1244,9 @@ computes whether we are in either of these cases.

Unlike normal functions, the compilation heuristics still can't generate good dispatch
in some cases, but this may still allow inference not to fall over in some limited cases.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function may_invoke_generator(mi::MethodInstance)
return may_invoke_generator(mi.def::Method, mi.specTypes, mi.sparam_vals)
Expand Down Expand Up @@ -1360,6 +1379,9 @@ end

Similar to [`code_typed`](@ref), except the argument is a tuple type describing
a full signature to query.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function code_typed_by_type(@nospecialize(tt::Type);
optimize=true,
Expand Down Expand Up @@ -1416,6 +1438,9 @@ The `Method` is included instead of `IRCode` otherwise.

See also: [`code_typed`](@ref)

!!! danger "Unstable"
This method is unstable and subject to change without notice.

# Internal Keyword Arguments

This section should be considered internal, and is only for who understands Julia compiler
Expand Down Expand Up @@ -1469,6 +1494,9 @@ end

Similar to [`code_ircode`](@ref), except the argument is a tuple type describing
a full signature to query.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function code_ircode_by_type(
@nospecialize(tt::Type);
Expand Down Expand Up @@ -1564,6 +1592,9 @@ end

Print type-inferred and optimized code for `f` given argument types `types`,
prepending each line with its cost as estimated by the compiler's inlining engine.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function print_statement_costs(io::IO, @nospecialize(f), @nospecialize(t); kwargs...)
tt = signature_type(f, t)
Expand Down Expand Up @@ -1781,6 +1812,9 @@ end
Find the keyword "body function" (the function that contains the body of the method
as written, called after all missing keyword-arguments have been assigned default values).
`basemethod` is the method you obtain via [`which`](@ref) or [`methods`](@ref).

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function bodyfunction(basemethod::Method)
fmod = parentmodule(basemethod)
Expand Down Expand Up @@ -1943,6 +1977,9 @@ end
delete_method(m::Method)

Make method `m` uncallable and force recompilation of any methods that use(d) it.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function delete_method(m::Method)
ccall(:jl_method_table_disable, Cvoid, (Any, Any), get_methodtable(m), m)
Expand All @@ -1956,6 +1993,9 @@ end
has_bottom_parameter(t) -> Bool

Determine whether `t` is a Type for which one or more of its parameters is `Union{}`.

!!! danger "Unstable"
This method is unstable and subject to change without notice.
"""
function has_bottom_parameter(t::DataType)
for p in t.parameters
Expand Down