From 19b3ca7be9f47099dcf192b57e3b044c571ed155 Mon Sep 17 00:00:00 2001 From: Jan Weidner Date: Sun, 8 Oct 2017 23:45:01 +0200 Subject: [PATCH] Add docstrings to exported modules (#23990) * Add docstrings to exported modules * Add docstrings to stdlib modules * fix docstring of Base * fix some module docstrings * fix --- base/distributed/Distributed.jl | 3 +++ base/docs/basedocs.jl | 5 +++++ base/iterators.jl | 3 +++ base/libc.jl | 3 +++ base/libdl.jl | 3 +++ base/libgit2/libgit2.jl | 3 +++ base/linalg/blas.jl | 3 +++ base/linalg/lapack.jl | 4 +++- base/linalg/linalg.jl | 5 +++++ base/markdown/Markdown.jl | 3 +++ base/meta.jl | 6 +++--- base/profile.jl | 3 +++ base/serialize.jl | 5 +++++ base/sparse/sparse.jl | 3 +++ base/stacktraces.jl | 3 +++ base/sysinfo.jl | 3 +++ base/threads.jl | 3 +++ doc/src/stdlib/base.md | 23 +++++++++++++++++++++ stdlib/DelimitedFiles/src/DelimitedFiles.jl | 4 ++++ stdlib/Mmap/src/Mmap.jl | 3 +++ stdlib/SharedArrays/src/SharedArrays.jl | 3 +++ 21 files changed, 90 insertions(+), 4 deletions(-) diff --git a/base/distributed/Distributed.jl b/base/distributed/Distributed.jl index 06e2bd9b06a6c..ebc8702805dd7 100644 --- a/base/distributed/Distributed.jl +++ b/base/distributed/Distributed.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Tools for distributed parallel processing. +""" module Distributed # imports for extension diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index 5d74c2dab343e..d57fdce6610cb 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -1496,4 +1496,9 @@ See the manual section on [Tuple Types](@ref). """ Tuple +""" +The base library of Julia. +""" +kw"Base" + end diff --git a/base/iterators.jl b/base/iterators.jl index 5a29cc9d77db1..cab61a9d0fc0d 100644 --- a/base/iterators.jl +++ b/base/iterators.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Methods for working with Iterators. +""" module Iterators import Base: start, done, next, isempty, length, size, eltype, iteratorsize, iteratoreltype, indices, ndims, pairs diff --git a/base/libc.jl b/base/libc.jl index 55f23400887c4..b6f76e3cb749f 100644 --- a/base/libc.jl +++ b/base/libc.jl @@ -1,6 +1,9 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license module Libc +@doc """ +Interface to libc, the C standard library. +""" -> Libc import Base: transcode diff --git a/base/libdl.jl b/base/libdl.jl index cd08d66cf2f78..9081709b971fb 100644 --- a/base/libdl.jl +++ b/base/libdl.jl @@ -1,6 +1,9 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license module Libdl +@doc """ +Interface to libdl. Provides dynamic linking support. +""" -> Libdl export DL_LOAD_PATH, RTLD_DEEPBIND, RTLD_FIRST, RTLD_GLOBAL, RTLD_LAZY, RTLD_LOCAL, RTLD_NODELETE, RTLD_NOLOAD, RTLD_NOW, dlclose, dlopen, dlopen_e, dlsym, dlsym_e, diff --git a/base/libgit2/libgit2.jl b/base/libgit2/libgit2.jl index af865cc920368..16da40e462b76 100644 --- a/base/libgit2/libgit2.jl +++ b/base/libgit2/libgit2.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Interface to [libgit2](https://libgit2.github.com/). +""" module LibGit2 import Base: merge!, == diff --git a/base/linalg/blas.jl b/base/linalg/blas.jl index 740bcd965ac9f..186750b7b6502 100644 --- a/base/linalg/blas.jl +++ b/base/linalg/blas.jl @@ -1,6 +1,9 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license module BLAS +@doc """ +Interface to BLAS subroutines. +""" -> BLAS import ..axpy!, ..axpby! import Base: copy! diff --git a/base/linalg/lapack.jl b/base/linalg/lapack.jl index 271674a992221..3cfc9b0427017 100644 --- a/base/linalg/lapack.jl +++ b/base/linalg/lapack.jl @@ -1,7 +1,9 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license -## The LAPACK module of interfaces to LAPACK subroutines module LAPACK +@doc """ +Interfaces to LAPACK subroutines. +""" -> LAPACK const liblapack = Base.liblapack_name diff --git a/base/linalg/linalg.jl b/base/linalg/linalg.jl index cf2d3c9e04e12..7bc879637a208 100644 --- a/base/linalg/linalg.jl +++ b/base/linalg/linalg.jl @@ -1,5 +1,10 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Linear algebra module. Provides array arithmetic, +matrix factorizations and other linear algebra related +functionality. +""" module LinAlg import Base: \, /, *, ^, +, -, == diff --git a/base/markdown/Markdown.jl b/base/markdown/Markdown.jl index 9f2155fb2c3b5..52df1347788f4 100644 --- a/base/markdown/Markdown.jl +++ b/base/markdown/Markdown.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Tools for working with the Markdown file format. Mainly for documentation. +""" module Markdown import Base: show, == diff --git a/base/meta.jl b/base/meta.jl index b5f5b8dc9d145..349b410ce9668 100644 --- a/base/meta.jl +++ b/base/meta.jl @@ -1,9 +1,9 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Convenience functions for metaprogramming. +""" module Meta -# -# convenience functions for metaprogramming -# export quot, isexpr, diff --git a/base/profile.jl b/base/profile.jl index ad89abdb88d2c..a6837d525f78d 100644 --- a/base/profile.jl +++ b/base/profile.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Profiling support, main entry point is the [`@profile`](@ref) macro. +""" module Profile import Base.StackTraces: lookup, UNKNOWN, show_spec_linfo diff --git a/base/serialize.jl b/base/serialize.jl index 62302040be93f..ffdc66526caf7 100644 --- a/base/serialize.jl +++ b/base/serialize.jl @@ -1,5 +1,10 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Provide serialization of Julia code via the functions +* [`serialize`](@ref) +* [`deserialize`](@ref) +""" module Serializer import Base: GMP, Bottom, unsafe_convert, uncompressed_ast diff --git a/base/sparse/sparse.jl b/base/sparse/sparse.jl index abe6289b18070..0c646964b2852 100644 --- a/base/sparse/sparse.jl +++ b/base/sparse/sparse.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Support for sparse arrays. Provides `AbstractSparseArray` and subtypes. +""" module SparseArrays using Base: ReshapedArray, promote_op, setindex_shape_check, to_shape, tail diff --git a/base/stacktraces.jl b/base/stacktraces.jl index a12d9c5888590..6b0c7069a2bb2 100644 --- a/base/stacktraces.jl +++ b/base/stacktraces.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Tools for collecting and manipulating stack traces. Mainly used for building errors. +""" module StackTraces diff --git a/base/sysinfo.jl b/base/sysinfo.jl index 434e9f1800945..def66c52e5225 100644 --- a/base/sysinfo.jl +++ b/base/sysinfo.jl @@ -1,6 +1,9 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license module Sys +@doc """ +Provide methods for retrieving information about hardware and the operating system. +""" -> Sys export CPU_CORES, WORD_SIZE, diff --git a/base/threads.jl b/base/threads.jl index d36cade097735..594584b384807 100644 --- a/base/threads.jl +++ b/base/threads.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Experimental multithreading support. +""" module Threads include("threadingconstructs.jl") diff --git a/doc/src/stdlib/base.md b/doc/src/stdlib/base.md index 5974274627f42..cf4f156c199d5 100644 --- a/doc/src/stdlib/base.md +++ b/doc/src/stdlib/base.md @@ -88,6 +88,29 @@ primitive type ; ``` +## Base Modules +```@docs +Base.BLAS +Base.Dates +Base.Distributed +Base.Docs +Base.Iterators +Base.LAPACK +Base.LibGit2 +Base.Libc +Base.Libdl +Base.LinAlg +Base.Markdown +Base.Meta +Base.Pkg +Base.Profile +Base.Serializer +Base.SparseArrays +Base.StackTraces +Base.Sys +Base.Threads +``` + ## All Objects ```@docs diff --git a/stdlib/DelimitedFiles/src/DelimitedFiles.jl b/stdlib/DelimitedFiles/src/DelimitedFiles.jl index 48fe7a9584657..9326ac78938db 100644 --- a/stdlib/DelimitedFiles/src/DelimitedFiles.jl +++ b/stdlib/DelimitedFiles/src/DelimitedFiles.jl @@ -2,6 +2,10 @@ __precompile__(true) +""" +Utilities for reading and writing delimited files, for example ".csv". +See [`readdlm`](@ref) and [`writedlm`](@ref). +""" module DelimitedFiles using Mmap diff --git a/stdlib/Mmap/src/Mmap.jl b/stdlib/Mmap/src/Mmap.jl index 0811bc1d3bedd..3ec31e0f84a6c 100644 --- a/stdlib/Mmap/src/Mmap.jl +++ b/stdlib/Mmap/src/Mmap.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Low level module for mmap (memory mapping of files). +""" module Mmap const PAGESIZE = Int(Sys.isunix() ? ccall(:jl_getpagesize, Clong, ()) : ccall(:jl_getallocationgranularity, Clong, ())) diff --git a/stdlib/SharedArrays/src/SharedArrays.jl b/stdlib/SharedArrays/src/SharedArrays.jl index 9d38aa2bfb864..585a10a8049de 100644 --- a/stdlib/SharedArrays/src/SharedArrays.jl +++ b/stdlib/SharedArrays/src/SharedArrays.jl @@ -1,5 +1,8 @@ # This file is a part of Julia. License is MIT: https://julialang.org/license +""" +Provide the [`SharedArray`](@ref) type. It represents an array, which is shared across multiple processes, on a single machine. +""" module SharedArrays using Mmap, Base.Distributed