Add a few missing docstrings for API docs (JuliaLang/JuliaSyntax.jl#301)

Author: c42f

JuliaSyntax/docs/make.jl

@@ -14,7 +14,8 @@ makedocs(;
     ],
     repo="https://github.com/JuliaLang/JuliaSyntax.jl/blob/{commit}{path}#L{line}",
     sitename="JuliaSyntax.jl",
-    authors = "Claire Foster and contributors: https://github.com/JuliaLang/JuliaSyntax.jl/graphs/contributors"
+    authors = "Claire Foster and contributors: https://github.com/JuliaLang/JuliaSyntax.jl/graphs/contributors",
+    strict = Documenter.except(:missing_docs)
 )
 
 deploydocs(;

JuliaSyntax/docs/src/api.md

@@ -13,11 +13,13 @@ JuliaSyntax.parseatom
 The `ParseStream` interface which provides a low-level stream-like I/O
 interface for writing the parser. The parser does not depend on or produce any
 concrete tree data structure as part of the parsing phase but the output spans
-can be post-processed into various tree data structures as required.
+can be post-processed into various tree data structures as required using
+[`JuliaSyntax.build_tree`](@ref).
 
 ```@docs
 JuliaSyntax.parse!
 JuliaSyntax.ParseStream
+JuliaSyntax.build_tree
 ```
 
 ## Tokenization
@@ -41,6 +43,8 @@ JuliaSyntax.source_location
 ## Expression heads/kinds
 
 ```@docs
+JuliaSyntax.Kind
+JuliaSyntax.SyntaxHead
 JuliaSyntax.@K_str
 JuliaSyntax.kind
 JuliaSyntax.head

JuliaSyntax/src/parse_stream.jl

@@ -69,12 +69,30 @@ end
 has_flags(flags::RawFlags, test_flags) = (flags & test_flags) != 0
 
 #-------------------------------------------------------------------------------
+"""
+    SyntaxHead(kind, flags)
+
+A `SyntaxHead` combines the [`Kind`](@ref) of a syntactic construct with a set
+of flags. The kind defines the broad "type" of the syntactic construct, while
+the flag bits compactly store more detailed information about the construct.
+"""
 struct SyntaxHead
     kind::Kind
     flags::RawFlags
 end
 
 kind(head::SyntaxHead) = head.kind
+
+"""
+    flags(x)
+
+Return the flag bits of a syntactic construct. Prefer to query these with the
+predicates `is_trivia`, `is_prefix_call`, `is_infix_op_call`,
+`is_prefix_op_call`, `is_postfix_op_call`, `is_dotted`, `is_suffixed`,
+`is_decorated`.
+
+Or extract numeric portion of the flags with `numeric_flags`.
+"""
 flags(head::SyntaxHead) = head.flags
 
 function Base.summary(head::SyntaxHead)

JuliaSyntax/src/source_files.jl

@@ -40,6 +40,10 @@ function _source_line_index(source::SourceFile, byte_index)
     return (lineidx < lastindex(source.line_starts)) ? lineidx : lineidx-1
 end
 _source_line(source::SourceFile, lineidx) = lineidx + source.first_line - 1
+
+"""
+Get the line number at the given byte index.
+"""
 source_line(source::SourceFile, byte_index) = _source_line(source, _source_line_index(source, byte_index))
 
 """

JuliaSyntax/src/syntax_tree.jl

@@ -96,6 +96,12 @@ haschildren(node::TreeNode) = node.children !== nothing
 children(node::TreeNode) = (c = node.children; return c === nothing ? () : c)
 
 
+"""
+    head(x)
+
+Get the [`SyntaxHead`](@ref) of a node of a tree or other syntax-related data
+structure.
+"""
 head(node::AbstractSyntaxNode) = head(node.raw)
 
 span(node::AbstractSyntaxNode) = span(node.raw)