API-INDEX
MODULE: Docile.Extensions
Modules [Exported]
Docile.Extensions Methods to extend how Docile handles parsing of docstrings.
Methods [Internal]
metamacro(::Docile.Formats.MetaMacro{:get, false}, body, mod, obj) Get the value stored in an object's metadata field.
metamacro(::Docile.Formats.MetaMacro{:include, false}, body, mod, obj) Splice the contents of a file in place of the metamacro call.
metamacro(::Docile.Formats.MetaMacro{:longform, false}, body, mod, obj) Make the contained text only appear in non-interactive output.
metamacro(::Docile.Formats.MetaMacro{:set, false}, body, mod, obj) Set the value for a field in an object's metadata.
metamacro(::Docile.Formats.MetaMacro{:summary, false}, body, mod, obj) Specify a short (120 character) summary for a docstring.
metamacro(::Docile.Formats.MetaMacro{:var, false}, body, mod, obj) Equivalent to !!set followed by !!get for the provided key.
MODULE: Docile
Modules [Exported]
Docile Documentation extraction package for the Julia Language.
MODULE: Docile.Interface
Functions [Exported]
parsedocs Parsing hook for specifying how to parse raw docstrings into formatted text.
Methods [Exported]
category{C}(::Docile.Legacy.Entry{C}) What category does an Entry object belong to?
data(d::Docile.Legacy.Docs{format}) Raw docstring associated with a Docs object d.
docs(e::Docile.Legacy.Entry{category}) The Docs object for an Entry object e.
documentation(mod::Module) The Metadata object associated with a module mod.
documented() Returns the modules that are currently documented by Docile.
entries(meta::Docile.Legacy.Metadata) ObjectIdDict containing documented objects and their associated Entrys.
files(meta::Docile.Legacy.Metadata) List of all included files in a module documented by Metadata object meta.
format{F}(d::Docile.Legacy.Docs{F}) The format that a docstring is written in.
isdocumented(mod::Module) Is the module mod documented by Docile?
isexported(modname::Module, object) Is the documented object object been exported from the given module modname?
isloaded(meta::Docile.Legacy.Metadata) Have the docstrings contained in a module been collected yet?
manual(meta::Docile.Legacy.Metadata) The manual files for a Metadata object meta.
metadata(e::Docile.Legacy.Entry{category}) Arbitrary additional metadata associated with a particular Entry e.
metadata(meta::Docile.Legacy.Metadata) The Dict{Symbol, Any} containing arbitrary additional data about a Metadata object.
metadata(mod::Module) Get the Metadata object associated with a module mod.
modulename(e::Docile.Legacy.Entry{category}) Which module does the Entry object come from?
modulename(meta::Docile.Legacy.Metadata) The Module that a Metadata object documents.
parsed(d::Docile.Legacy.Docs{format}) Get the parsed docstring for a Docs object d.
root(meta::Docile.Legacy.Metadata) The rootfile of the module documented by a Metadata object meta.
Functions [Internal]
name Get the Symbol representing an object such as Function or Method.
Globals [Internal]
DOCUMENTED Storage for deprecated Metadata documentation.
MODULE: Docile.Runner
Methods [Exported]
findmethods(state::Docile.Runner.State, ex::Expr, codesource) Find all methods defined by an method definition expression.
findtuples(state::Docile.Runner.State, expr::Expr) Find the Method objects referenced by (...) docstring syntax.
findvcats(state::Docile.Runner.State, expr::Expr) Find Function and Method objects referenced by [...] syntax.
withref(fn, state, ref) Push reference onto state, run function block, and pop reference afterwards.
Types [Exported]
Docile.Runner.State Hold state for use with exec to determine the objects referenced by symbols.
Methods [Internal]
addtoscope!(state, var, value) Add new variable and it's value to topmost scope.
exec(state::Docile.Runner.State, expr::Expr) Evaluate the expression expr within the context provided by state.
funcname(state::Docile.Runner.State, expr::Expr) Return the Function object represented by a method definition expression.
getargs(expr::Expr) Extract the expressions representing a method definition's arguments.
gettvars(expr::Expr) Extract the expressions from a {} in a function definition.
lineinfo(m::Method) Line number and file name pair for a method m.
MODULE: Docile.Utilities
Methods [Exported]
parsefile(file::AbstractString) Retrieve the Expr object from a Julia source file file.
Methods [Internal]
init_cache() Check cache directory for up to date version directory. Remove older version
init_cache(cache) Check cache directory for up to date version directory. Remove older version
init_cache(cache, current) Check cache directory for up to date version directory. Remove older version
expandpath(path) Convert a path to absolute. Relative paths are guessed to be from Julia /base.
message(msg::AbstractString) Print a 'Docile'-formatted message to STDOUT.
path_id(file::AbstractString) Returns the cache path for a given file file.
samemodule(mod, def::Method) Is the module where a function/method is defined the same as mod?
Globals [Internal]
BASE Path to Julia's base source code.
CACHE_CUR The current versioned cache subdirectory set by CACHE_VER
CACHE_DIR Path to Docile's main cache folder.
CACHE_VER Internal version of the cache structure.
MODULE: Docile.Legacy
Macros [Exported]
@comment(text) Deprecated macro for adding object-independent docstrings to a module.
@file_str(text) The text found in the file text is used as the docstring content.
Methods [Internal]
call(::Type{Docile.Legacy.Manual}, ::Void, files) Usage from REPL, use current directory as root.
data(n, docstr) Assign to docs to n and return a dictionary of keyword arguments.
doc(expr::Expr) Main documentation generation routine.
doc(expr::Expr, generic) Main documentation generation routine.
doc(s::Symbol, ex::Expr) Detect '@doc+' syntax in macro call.
lateguess(::Function) Return the category of an object.
nameof(x::Expr) Get the symbolic name of an expression.
unarrow(x::Expr) Extract the docstring and expression to be documented from an -> expression.
unblock(x::Expr) Extract the line number and documented object expression from a block.
Macros [Internal]
@doc(ex) Document an object.
@init() Setup macro-style documentation datastructures.
MODULE: Docile.Formats
Methods [Exported]
parsedocs(::Docile.Formats.Format{F<:Docile.Formats.AbstractFormatter}, raw, mod, obj) Parsing hook for docstring parsing.
Methods [Internal]
applymeta(name, body, mod, obj) Apply nesting to body of metamacro when defined otherwise treat as raw text.
extractmeta!(text::AbstractString, mod::Module, obj) Run all 'metamacros' found in a raw docstring and return the resulting string.
isprefix(io::IO, chars) Does the buffer io begin with the given prefix chars?
isvalid(s::AbstractString) Check that a MetaMacro's name is a valid identifier.
readbracketed(io::IO) Extract to a string the text between matching brackets ( and ).
tryextract(io::IO) Try extract an embedded metadata entry name from buffer at current position.
Types [Internal]
Docile.Formats.MetaMacro{name, raw} Dispatch type for the metamacro function. name is a Symbol.
Macros [Internal]
@META_str(args...) Shorthand syntax for defining MetaMacro{<name>}s as META"<name>".
MODULE: Docile.Cache
Methods [Exported]
clear!() Empty the documentation cache of all data.
getmeta(m::Module) Get the metadata dictionaries for all documented objects in a module.
getmeta(m::Module, obj) Get the Dict{Symbol, Any} containing an object's metadata.
getparsed(m::Module) Get the parsed docstrings associated with all documented objects in a module.
getparsed(m::Module, obj) Get the parsed form of a docstring associated with an object obj.
getraw(m::Module) Get the raw docstrings associated with all documented objects in a module.
getraw(m::Module, obj) Get the raw docstring associated with a documented object obj in module m.
objects(m::Module) Return all documented objects found in a module m.
Methods [Internal]
extractor!(cache::Docile.Cache.GlobalCache, raw::AbstractString, m::Module, obj) Extract metadata embedded in docstrings and run the parsedocs method defined
findmeta(m::Module, obj, key::Symbol, T) Find the metadata for key associated with an object obj in module m.
getmodule(m::Module) Get the ModuleData object associated with a module m.
getpackage(m::Module) Get the PackageData object associated with a module m.
loadedmodules() Returns the set of all loaded modules.
parse!(cache::Docile.Cache.GlobalCache, m::Module) Parse raw docstrings in module m into their parsed form.
togglebase() Turn on documenting of Base and it's submodules. Off by default.
Types [Internal]
Docile.Cache.DocsCache For a single module store raw docstrings, parsed docs, and metadata.
MODULE: Docile.Collector
Functions [Internal]
isdocstring Does the expression represent a docstring?
name Extract the symbol identifying an expression.
process! Extract all docstrings and metadata from a given file
recheck Convert category from :symbol to either :module or :function.
Methods [Internal]
definedmodules!(out, expr::Expr) Return the set of toplevel modules that are defined in an expression.
docstrings(m::Docile.Collector.ModuleData) Extract all docstrings and basic metadata (file, line, & code) from a module.
findexternal(docs) Check whether a docstring is acutally a file path. Read that instead if it is.
findmodule(expr::Expr, mod::Module) Extract the module expression corresponding to a Module object.
findpackages(rootfiles::Set{UTF8String}) Return the PackageData objects associated with a set of files.
get_aside!(output, moddata, state, file, block) Extract the comment block from expressions and capture metadata.
get_docs!(output, moduledata, state, file, block) Extract a docstring and associated object(s) as well as metadata.
getcategory(x) The category of an expression. :symbol is resolved at a later stage by recheck.
getdotfile(dir::AbstractString) Check for a .docile configuration file in the directory dir.
getobject(::Docile.Utilities.Head{:macro}, moduledata, state, expr, ::Any) Get the (anonymous function) object defined by a macro expression.
getobject(::Docile.Utilities.Head{:method}, moduledata, state, expr, codesource) Find all Method objects defined by a given expression.
getobject(::Docile.Utilities.Head{:tuple}, ::Any, state, expr, ::Any) Find group of methods that match a provided signature.
getobject(::Union{Docile.Utilities.Head{:vcat}, Docile.Utilities.Head{:vect}}, ::Any, state, expr, ::Any) Find a set of methods and a set of functions that match the provided vector.
getobject(cat::Symbol, moduledata, state, expr, codesource) Find all objects described by an expression.
includedfiles(mod::Module, candidates::Set{T}) Which source files are known to be included in a module.
is_aside(block) Is the tuple a valid comment block?
isdocblock(block) Does the tuple of expressions represent a valid docstring and associated object?
isrootfile(mod::Symbol, parsed::Expr) Is the file the root for a module mod. Check for Expr(:module, ...).
isrootmodule(m::Module) Is the module a toplevel one not including the module Main?
location(object::Method) Path to definition of a julia object, only methods are searched for.
postprocess!(cat::Symbol, metadata, ex) Add some additional metadata for macros and method definitions.
samemodule(expr, mod) Does the expression expr represent the module name mod?
skipexpr(x) Blacklist some expressions so search doesn't decend into them.
store!(output, object, docs, metadata) Save docstrings and metadata for the objects that have been found.
submodules(mod::Module) Return the set of all submodules of a given module mod.
Types [Internal]
Docile.Collector.Output Temporary container used for docstring processing. Not the final storage.