Skip to content
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.

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

add tests for undocumented symbols #52723

Merged
merged 31 commits into from
Jan 14, 2024
Merged
Show file tree
Hide file tree
Changes from 23 commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
8fcbfe5
add tests for undocumented symbols
stevengj Jan 3, 2024
ccbe7da
Iterators is documented
stevengj Jan 3, 2024
0a9cbe9
Docs test not broken
stevengj Jan 3, 2024
5a4da88
use isempty rather than == []
stevengj Jan 4, 2024
a387859
use isempty rather than == []
stevengj Jan 4, 2024
5f6dfa6
use isempty rather than == []
stevengj Jan 4, 2024
580d3ee
missing Broadcast.dotview
stevengj Jan 4, 2024
75b5ff7
Update checked.jl: docstring check
stevengj Jan 4, 2024
cd41582
Update math.jl: MathConstants docstrings
stevengj Jan 4, 2024
4344981
Update ordering.jl: missing docstrings check
stevengj Jan 4, 2024
596987a
Update test/ordering.jl
stevengj Jan 4, 2024
a7cf9d3
Update sorting.jl: Base.Sort docstrings
stevengj Jan 4, 2024
6eea5aa
Merge branch 'master' into test_undoc
stevengj Jan 4, 2024
b48973e
Update stdlib/Markdown/test/runtests.jl
stevengj Jan 4, 2024
f94c1fc
Update test/docs.jl
stevengj Jan 4, 2024
bf0185d
need to import Base64 module name too
stevengj Jan 4, 2024
91169ed
InteractiveUtils.apropos is public
stevengj Jan 4, 2024
2b7fa9c
apropos has a docstring
stevengj Jan 4, 2024
939b21c
document apropos and doc in the Base.Docs module where they are defin…
stevengj Jan 5, 2024
53933d9
comment fix
stevengj Jan 5, 2024
95c3491
rm redundant docstring for doc
stevengj Jan 5, 2024
a292322
add missing docstring for WindowsRawSocket
stevengj Jan 6, 2024
4cf784a
Merge branch 'master' into test_undoc
stevengj Jan 6, 2024
abb225c
Update stdlib/Markdown/test/runtests.jl
stevengj Jan 6, 2024
8564922
Merge branch 'master' into test_undoc
stevengj Jan 6, 2024
c875e5e
Merge branch 'master' into test_undoc
stevengj Jan 8, 2024
45caec6
unicode docs now merged
stevengj Jan 9, 2024
9718104
Update broadcast.jl: missing "end"
stevengj Jan 9, 2024
8887460
Merge branch 'master' into test_undoc
stevengj Jan 9, 2024
91e465d
Update libc.jl: use doc macro to document inside if ... end
stevengj Jan 10, 2024
f286d44
Merge branch 'master' into test_undoc
LilithHafner Jan 14, 2024
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
28 changes: 27 additions & 1 deletion base/docs/Docs.jl
Original file line number Diff line number Diff line change
Expand Up @@ -650,11 +650,37 @@ function loaddocs(docs::Vector{Core.SimpleVector})
nothing
end

# FIXME: formatdoc, parsedoc, apropos, and doc are defined here (but only doc is exported)
# for historical reasons (#25738), but are *implemented* in REPL/src/docview.jl, while
# apropos is *exported* by InteractiveUtils and doc is exported by Docs. Seems
# like a more sensible refactoring should be possible.

function formatdoc end
function parsedoc end

"""
apropos([io::IO=stdout], pattern::Union{AbstractString,Regex})
Search available docstrings for entries containing `pattern`.
When `pattern` is a string, case is ignored. Results are printed to `io`.
`apropos` can be called from the help mode in the REPL by wrapping the query in double quotes:
```
help?> "pattern"
```
"""
function apropos end
function doc end

"""
Docs.doc(binding, sig)
Return all documentation that matches both `binding` and `sig`.
If `getdoc` returns a non-`nothing` result on the value of the binding, then a
dynamic docstring is returned instead of one based on the binding itself.
"""
function doc end
stevengj marked this conversation as resolved.
Show resolved Hide resolved

"""
Docs.hasdoc(mod::Module, sym::Symbol)::Bool
Expand Down
5 changes: 5 additions & 0 deletions base/libc.jl
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@ show(io::IO, fd::RawFD) = print(io, "RawFD(", bitcast(UInt32, fd), ')') # avoid

# Wrapper for an OS file descriptor (for Windows)
if Sys.iswindows()
"""
WindowsRawSocket

Primitive type which wraps the native Windows file `HANDLE`.
"""
primitive type WindowsRawSocket sizeof(Ptr) * 8 end # On Windows file descriptors are HANDLE's and 64-bit on 64-bit Windows
WindowsRawSocket(handle::Ptr{Cvoid}) = bitcast(WindowsRawSocket, handle)
WindowsRawSocket(handle::WindowsRawSocket) = handle
Expand Down
6 changes: 6 additions & 0 deletions stdlib/Artifacts/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -261,3 +261,9 @@ end
@test length(Base.manifest_names) == 2n # there are two manifest names per project name
@test length(Base.preferences_names) == n
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Artifacts)
@test_broken isempty(undoc)
@test undoc == [:Artifacts]
end
7 changes: 6 additions & 1 deletion stdlib/Base64/test/runtests.jl
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# This file is a part of Julia. License is MIT: https://julialang.org/license

using Test, Random
import Base64:
using Base64:
Base64,
Base64EncodePipe,
base64encode,
Base64DecodePipe,
Expand Down Expand Up @@ -142,3 +143,7 @@ end
@test String(base64decode(splace(longEncodedText))) == longDecodedText
end
end

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(Base64))
end
4 changes: 4 additions & 0 deletions stdlib/CRC32c/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,7 @@ end
crc32c_sw(io::IO, crc::UInt32=0x00000000) = crc32c_sw(io, typemax(Int64), crc)
test_crc32c(crc32c)
test_crc32c(crc32c_sw)

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(CRC32c))
end
8 changes: 8 additions & 0 deletions stdlib/Dates/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,16 @@

module DateTests

using Test, Dates

for file in readlines(joinpath(@__DIR__, "testgroups"))
include(file * ".jl")
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Dates)
@test_broken isempty(undoc)
@test undoc == [:adjust]
end

end
6 changes: 6 additions & 0 deletions stdlib/FileWatching/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -447,4 +447,10 @@ rm(dir)
include("pidfile.jl")
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(FileWatching)
@test_broken isempty(undoc)
@test undoc == [:FDWatcher, :FileMonitor, :FolderMonitor, :PollingFileWatcher]
end

end # testset
4 changes: 4 additions & 0 deletions stdlib/Future/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,7 @@

using Test
using Future

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(Future))
end
6 changes: 6 additions & 0 deletions stdlib/InteractiveUtils/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -721,3 +721,9 @@ end
end

@test Base.infer_effects(sin, (Int,)) == InteractiveUtils.@infer_effects sin(42)

@testset "Docstrings" begin
undoc = Docs.undocumented_names(InteractiveUtils)
@test_broken isempty(undoc)
@test undoc == [:InteractiveUtils]
end
7 changes: 6 additions & 1 deletion stdlib/LibGit2/test/runtests.jl
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
# This file is a part of Julia. License is MIT: https://julialang.org/license

using Test
using Test, LibGit2

@testset verbose=true "LibGit2 $test" for test in eachline(joinpath(@__DIR__, "testgroups"))
include("$test.jl")
end

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(LibGit2))
end
6 changes: 6 additions & 0 deletions stdlib/Libdl/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -329,3 +329,9 @@ end
lazy_name_lazy_lib = LazyLibrary(libname)
@test dlpath(lazy_name_lazy_lib) == realpath(string(libname))
end; end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Libdl)
@test_broken isempty(undoc)
@test undoc == [:Libdl]
end
7 changes: 7 additions & 0 deletions stdlib/LinearAlgebra/test/runtests.jl
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# This file is a part of Julia. License is MIT: https://julialang.org/license
using Test, LinearAlgebra

for file in readlines(joinpath(@__DIR__, "testgroups"))
include(file * ".jl")
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(LinearAlgebra)
@test_broken isempty(undoc)
@test undoc == [:ColumnNorm, :LAPACKException, :NoPivot, :RankDeficientException, :RowMaximum, :RowNonZero, :copy_transpose!]
end
6 changes: 6 additions & 0 deletions stdlib/Logging/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -300,4 +300,10 @@ end
@test occursin("CustomLog2: hello", String(take!(buf)))
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Logging)
@test_broken isempty(undoc)
@test undoc == [:AboveMaxLevel, :BelowMinLevel]
end

end
6 changes: 6 additions & 0 deletions stdlib/Markdown/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1293,3 +1293,9 @@ end
# see issue #42139
@test md"<一轮红日初升>" |> html == """<p>&lt;一轮红日初升&gt;</p>\n"""
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Markdown)
@test_broken isempty(undoc)
@test undoc == [Symbol("@doc_str"), Symbol("@md_str"), :html, :latex]
stevengj marked this conversation as resolved.
Show resolved Hide resolved
end
4 changes: 4 additions & 0 deletions stdlib/Mmap/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -339,3 +339,7 @@ open(file, "r+") do s
finalize(A); A = nothing; GC.gc()
end
rm(file)

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(Mmap))
end
6 changes: 6 additions & 0 deletions stdlib/Printf/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1145,4 +1145,10 @@ end
@test_throws Printf.InvalidFormatStringError Printf.Format("%z")
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Printf)
@test_broken isempty(undoc)
@test undoc == [:Printf]
end

end # @testset "Printf"
6 changes: 6 additions & 0 deletions stdlib/Profile/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -300,3 +300,9 @@ end
end

include("allocs.jl")

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Profile)
@test_broken isempty(undoc)
@test undoc == [:Allocs]
end
20 changes: 0 additions & 20 deletions stdlib/REPL/src/docview.jl
Original file line number Diff line number Diff line change
Expand Up @@ -198,14 +198,6 @@ function insert_internal_warning(other, internal_access::Set{Pair{Module,Symbol}
other
end

"""
Docs.doc(binding, sig)
Return all documentation that matches both `binding` and `sig`.
If `getdoc` returns a non-`nothing` result on the value of the binding, then a
dynamic docstring is returned instead of one based on the binding itself.
"""
function doc(binding::Binding, sig::Type = Union{})
if defined(binding)
result = getdoc(resolve(binding), sig)
Expand Down Expand Up @@ -920,18 +912,6 @@ stripmd(x::Markdown.Footnote) = "$(stripmd(x.id)) $(stripmd(x.text))"
stripmd(x::Markdown.Table) =
join([join(map(stripmd, r), " ") for r in x.rows], " ")

"""
apropos([io::IO=stdout], pattern::Union{AbstractString,Regex})
Search available docstrings for entries containing `pattern`.
When `pattern` is a string, case is ignored. Results are printed to `io`.
`apropos` can be called from the help mode in the REPL by wrapping the query in double quotes:
```
help?> "pattern"
```
"""
apropos(string) = apropos(stdout, string)
apropos(io::IO, string) = apropos(io, Regex("\\Q$string", "i"))

Expand Down
6 changes: 6 additions & 0 deletions stdlib/REPL/test/repl.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1749,3 +1749,9 @@ let io = IOBuffer()
seek(io, 0)
@test countlines(io) == 2
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(REPL)
@test_broken isempty(undoc)
@test undoc == [:AbstractREPL, :BasicREPL, :LineEditREPL, :StreamREPL]
end
4 changes: 4 additions & 0 deletions stdlib/Random/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1232,3 +1232,7 @@ end
@test xs isa Vector{Pair{Bool, Char}}
@test length(xs) == 3
end

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(Random))
end
6 changes: 6 additions & 0 deletions stdlib/Serialization/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -655,3 +655,9 @@ end
@test l2 == l1
@test l2.parts === ()
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Serialization)
@test_broken isempty(undoc)
@test undoc == [:AbstractSerializer, :Serializer]
end
4 changes: 4 additions & 0 deletions stdlib/SharedArrays/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -324,3 +324,7 @@ end
@test SharedMatrix([0.1 0.2; 0.3 0.4]) == [0.1 0.2; 0.3 0.4]
@test_throws MethodError SharedVector(rand(4,4))
@test_throws MethodError SharedMatrix(rand(4))

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(SharedArrays))
end
4 changes: 4 additions & 0 deletions stdlib/Sockets/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -682,3 +682,7 @@ end


close(sockets_watchdog_timer)

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(Sockets))
end
6 changes: 6 additions & 0 deletions stdlib/TOML/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,9 @@ include("print.jl")
include("parse.jl")

@inferred TOML.parse("foo = 3")

@testset "Docstrings" begin
undoc = Docs.undocumented_names(TOML)
@test_broken isempty(undoc)
@test undoc == [:TOML]
end
4 changes: 4 additions & 0 deletions stdlib/Test/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1582,3 +1582,7 @@ let
end
end
end

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(Test))
end
4 changes: 4 additions & 0 deletions stdlib/UUIDs/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,7 @@ str = "22b4a8a1-e548-4eeb-9270-60426d66a48e"
for r in rand(UInt128, 10^3)
@test UUID(r) == UUID(string(UUID(r)))
end

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(UUIDs))
end
6 changes: 6 additions & 0 deletions stdlib/Unicode/test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -534,3 +534,9 @@ isequal_normalized_naive(s1, s2; kws...) = normalize(s1; kws...) == normalize(s2
@test !isequal_normalized("x\u0334\u0335", "x\u0335\u0334")
end
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Unicode)
@test_broken isempty(undoc)
@test undoc == [:Unicode]
end
6 changes: 6 additions & 0 deletions test/broadcast.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1175,3 +1175,9 @@ import Base.Broadcast: BroadcastStyle, DefaultArrayStyle

f51129(v, x) = (1 .- (v ./ x) .^ 2)
@test @inferred(f51129([13.0], 6.5)) == [-3.0]

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Broadcast)
@test_broken isempty(undoc)
@test undoc == [:dotview]
end
4 changes: 4 additions & 0 deletions test/checked.jl
Original file line number Diff line number Diff line change
Expand Up @@ -358,3 +358,7 @@ end
@test checked_mul(1, 2, 3, 4, 5, 6, 7) === 5040
@test checked_mul(1, 2, 3, 4, 5, 6, 7, 8) === 40320
end

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(Base.Checked))
end
6 changes: 6 additions & 0 deletions test/docs.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1556,3 +1556,9 @@ Base.@ccallable c51586_long()::Int = 3

@test docstrings_equal(@doc(c51586_short()), doc"ensure we can document ccallable functions")
@test docstrings_equal(@doc(c51586_long()), doc"ensure we can document ccallable functions")

@testset "Docs docstrings" begin
undoc = Docs.undocumented_names(Docs)
@test_broken isempty(undoc)
@test undoc == [Symbol("@var")]
end
6 changes: 6 additions & 0 deletions test/filesystem.jl
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,9 @@
@test S_IRUSR & ~S_IRGRP == S_IRUSR
@test typeof(S_IRUSR) == typeof(S_IRGRP) == typeof(S_IROTH)
end

@testset "Base.Filesystem docstrings" begin
undoc = Docs.undocumented_names(Base.Filesystem)
@test_broken isempty(undoc)
@test undoc == [:File, :Filesystem, :JL_O_APPEND, :JL_O_ASYNC, :JL_O_CLOEXEC, :JL_O_CREAT, :JL_O_DIRECT, :JL_O_DIRECTORY, :JL_O_DSYNC, :JL_O_EXCL, :JL_O_FSYNC, :JL_O_LARGEFILE, :JL_O_NDELAY, :JL_O_NOATIME, :JL_O_NOCTTY, :JL_O_NOFOLLOW, :JL_O_NONBLOCK, :JL_O_PATH, :JL_O_RANDOM, :JL_O_RDONLY, :JL_O_RDWR, :JL_O_RSYNC, :JL_O_SEQUENTIAL, :JL_O_SHORT_LIVED, :JL_O_SYNC, :JL_O_TEMPORARY, :JL_O_TMPFILE, :JL_O_TRUNC, :JL_O_WRONLY, :S_IRGRP, :S_IROTH, :S_IRUSR, :S_IRWXG, :S_IRWXO, :S_IRWXU, :S_IWGRP, :S_IWOTH, :S_IWUSR, :S_IXGRP, :S_IXOTH, :S_IXUSR, :cptree, :futime, :rename, :sendfile, :unlink]

Check warning on line 47 in test/filesystem.jl

View workflow job for this annotation

GitHub Actions / Check for new typos

perhaps "WRONLY" should be "WRONGLY".
end
4 changes: 4 additions & 0 deletions test/gc.jl
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,7 @@ end
run_gctest("gc/chunks.jl")
run_nonzero_page_utilization_test()
end

@testset "Base.GC docstrings" begin
@test isempty(Docs.undocumented_names(GC))
end
4 changes: 4 additions & 0 deletions test/iterators.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1009,3 +1009,7 @@ end
@testset "collect partition substring" begin
@test collect(Iterators.partition(lstrip("01111", '0'), 2)) == ["11", "11"]
end

@testset "Iterators docstrings" begin
@test isempty(Docs.undocumented_names(Iterators))
end
4 changes: 4 additions & 0 deletions test/math.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1599,3 +1599,7 @@ end === Float64
@test tanpi(big(1//1)) == big(0.0)
@test cospi(big(1//1)) == big(-1.0)
end

@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(MathConstants))
end
Loading