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
JuliaLang · Oct 8, 2017 · 19b3ca7 · 19b3ca7
1 parent d377713
commit 19b3ca7
Show file tree

Hide file tree

Showing 21 changed files with 90 additions and 4 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
-Original file line number
+Diff line change
@@ Expand Up / @@ -1496,4 +1496,9 @@ See the manual section on [Tuple Types](@ref). @@
     """
     Tuple
+    """
+    The base library of Julia.
+    """
+    kw"Base"
     end