Update docs

docs/building.dox

@@ -111,7 +111,7 @@ This section contains instructions for building the documentation.
 
 ## Dependencies
 
-- [doxygen](http://www.doxygen.nl/) - at least 1.8.17
+- [doxygen](http://www.doxygen.nl/) - at least 1.9
 
 ## Steps
 
@@ -187,5 +187,4 @@ target_link_libraries(example PRIVATE slang::slang)
 
 See [this GitHub project](https://github.com/MikePopoloski/slang_subproject_example) as an example of integrating slang using this method.
 
-
 */

docs/command-line-ref.dox

@@ -19,7 +19,7 @@ Don't print non-essential output status.
 
 `positional arguments`
 
-Paths to files that should be included in the compilation.
+Paths to files (using @ref file-patterns "file patterns") that should be included in the compilation.
 
 `--single-unit`
 
@@ -28,25 +28,26 @@ By default all files are considered to be separate compilation units and orderin
 does not matter. When this option is provided, all files are concatenated together, in order, to
 produce a single compilation unit.
 
-`-v <filename>`
+`-v <file-pattern>[,...]`
 
-Adds a file to the compilation, like a positional argument, except that the file is
-considered to be a Verilog library. Libraries are always their own compilation unit even
-when compiling with `--single-unit`, and modules within them are never automatically instantiated.
+Adds files to the compilation, like a positional argument, except that the files are
+considered to be Verilog @ref source-libraries "source libraries". Libraries are always their
+own compilation unit even when compiling with `--single-unit`, and modules within them are
+never automatically instantiated.
 
-`-f <filename>`
+`-f <file-pattern>[,...]`
 
-Opens the given "command file" containing lists of arguments to process in
+Opens the given "command files" containing lists of arguments to process in
 addition to the ones provided on the command line itself. Any file paths in
-the file are relative to the current working directory.
+the files are relative to the current working directory.
 
 See @ref command-files for more information about command files.
 
-`-F <filename>`
+`-F <file-pattern>[,...]`
 
-Opens the given "command file" containing lists of arguments to process in
+Opens the given "command files" containing lists of arguments to process in
 addition to the ones provided on the command line itself. Any file paths in
-the file are relative to the command file itself.
+the files are relative to the command file itself.
 
 See @ref command-files for more information about command files.
 
@@ -95,16 +96,16 @@ Only perform linting of code, don't try to elaborate a full hierarchy.
 @section include-paths Include paths and macros
 
 ```
--I,--include-directory <dir>
+-I,--include-directory <dir-pattern>[,...]
 +incdir+<dir>[+<dir>...]
 ```
 
-Add the given directory path to the list of directories searched by \`include directives that use
+Add the given directory paths to the list of directories searched by \`include directives that use
 quotes to specify the path.
 
-`--isystem <dir>`
+`--isystem <dir-pattern>[,...]`
 
-Add the given directory path to the list of directories searched by \`include directives that use
+Add the given directory paths to the list of directories searched by \`include directives that use
 angle brackets to specify the path.
 
 ```
@@ -161,9 +162,9 @@ stack, which is checked against this limit to avoid stack overflows. The default
 Set the maximum number of errors that can occur during lexing before the rest of the file is skipped.
 The default is 64.
 
-`-y,--libdir <dir>`
+`-y,--libdir <dir-pattern>[,...]`
 
-Add the given directory path to the list of directories searched when an unknown module instantiation
+Add the given directory paths to the list of directories searched when an unknown module instantiation
 or package import is encountered. Combined with `--libext`, files are automatically included based on the
 name that is unknown. This list is empty by default.
 
@@ -173,6 +174,8 @@ names that reference a name not in the list of known definitions will trigger a
 directories, trying all specified library extensions. If a matching file is found it will be loaded and
 parsed in its entirety, and the algorithm will be triggered again on any new names found.
 
+See @ref library-search for more details.
+
 `-Y,--libext <ext>`
 
 Add the given extension to the list of extensions tried when searching for files to satisfy
@@ -317,12 +320,12 @@ Show or hide macro expansion backtraces in diagnostic output. The default is to
 
 Show or hide hierarchy locations in diagnostic output. The default is to show.
 
-`--suppress-warnings`
+`--suppress-warnings <file-pattern>[,...]`
 
 One or more paths in which to suppress warnings. Use this if you want to generally turn on warnings
 for your project and have it build cleanly but have some files which you can't modify for some reason.
 
-`--suppress-macro-warnings`
+`--suppress-macro-warnings <file-pattern>[,...]`
 
 One or more paths in which to suppress warnings that originate from macro expansions. This means that
 warnings inside of macros that are defined within these paths will be suppressed, even if the macros are

docs/common-components.dox

@@ -10,8 +10,6 @@ C++20.
 analysis.
 - clang-format enforces stylistic conventions
 - Types and constants are PascalCase, functions and members are camelCase.
-- Some common standard library components are included and exposed via Util.h
-which is widely included throughout the library.
 - slang is intended to be used as a library in other programs, possibly in
 multithreaded scenarios, so global state or code that affects the environment
 is not allowed.

docs/diagnostics.dox

@@ -38,7 +38,7 @@ issue, options that can hide all or some subset of warnings, and the ability to
 remap the default severity of a given diagnostic code.
 
 Each Diagnostic that is issued to a DiagnosticEngine is formatted and, assuming
-it's not supressed, forwarded to all registered @ref slang::DiagnosticClient
+it's not suppressed, forwarded to all registered @ref slang::DiagnosticClient
 instances. Clients are registered with the engine via
 @ref slang::DiagnosticEngine::addClient. It's the client's job to actually do
 something with the diagnostic; for example, it may write the text to an internal

docs/parsing.dox

@@ -139,8 +139,20 @@ diagnostics that occurred.
 Parsing text is then as easy as:
 
 @code{.cpp}
-auto tree1 = SyntaxTree::fromFile("path/to/file.sv");
-auto tree2 = SyntaxTree::fromText("module m; endmodule");
+auto tree = SyntaxTree::fromText("module m; endmodule");
+@endcode
+
+When loading from a file the result also includes (via a std::expected object)
+a system error code if the load fails.
+
+@code{.cpp}
+auto result = SyntaxTree::fromFile("path/to/file.sv");
+if (result) {
+    /* do something with *result */
+}
+else {
+    /* do something with result.error() */
+}
 @endcode
 
 @section syntax-visitor Manipulating the syntax tree

docs/user-manual.dox

@@ -54,6 +54,23 @@ endmodule
 Build failed: 1 error, 0 warnings
 @endcode
 
+@section file-patterns File Patterns
+
+All inputs to slang that accept a file path also accept a file "pattern", which is
+a wildcarded pattern that can select zero or more files (or directories, for options
+like `-I`). Allowed shortcuts/wildcards are:
+-   `?` matches any single character
+-   `*` matches zero or more characters
+-   `...` recursively matches any number of directories
+-   `..` specifies the parent directory
+-   `.` specifies the current directory
+
+Paths that end in a `/` include all the files in that directory, identical to \c /\*.
+
+@note File patterns provided on the command line will first be seen by your shell;
+be aware that it may be expanded before slang even sees it, which can cause
+unintuitive results.
+
 @section compilation-units Compilation Units
 
 By default `slang` treats all input files as separate SystemVerilog compilation units.
@@ -65,14 +82,64 @@ parsed in a specific order.
 If you have an older project where file ordering does matter, you can pass the `--single-unit`
 option to have all input files treated as a single compilation unit.
 
-@section built-in-macros Built-in Macros
+@section source-libraries Source Libraries
 
-There are a handful of slang-specific predefined macros that you can reference in your code:
-Name | Value
----- | -----
-\`__slang__ | 1
-\`__slang_major__ | *slang major version number*
-\`__slang_minor__ | *slang minor version number*
+SystemVerilog has a concept of a "source library" which is a named collection of files that
+can be included in a design. All files are part of a source library -- if none is named
+explicitly for a given file, that file will be part of the default library (named "work").
+
+Library files can be specified on the command line using the `-v` option, which accepts
+a file pattern and an optional library name. If the library name is ommitted, the file
+is placed in the default library. For example:
+
+@code{.ansi}
+> slang top_module.sv -v some/lib1.sv -v "my_lib=some/other/lib2.sv"
+@endcode
+
+This includes three files in the design; top_module.sv is a non-library file (though it
+is placed in the default "work" library for purposes of having a library name available),
+lib1.sv is a library file in the "work" library, and lib2.sv is a library file in the
+"my_lib" library.
+
+The distinction between library files and non-library files is that modules in
+library files are never automatically instantiated, unused code elements don't cause
+warnings, and unused modules have no semantic error checking applied (e.g. name lookups
+don't occur, though the files must still be syntactically correct SystemVerilog code).
+Also it is assumed that library files are independent from each other even if the
+`--single-unit` flag is used (and thus can be loaded and parsed in any order).
+If you are using `--single-unit` and need macros declared in the regular files to be
+visible in library files you can use the `--libraries-inherit-macros` flag.
+
+Libraries can also be defined using "library map" files, which are passed to slang
+using the `--libmap` flag. The format of library map files is specified in the
+SystemVerilog LRM, section 33.3. An example map file might look like:
+
+@code{.sv}
+include some/other/lib.map
+
+// Declare a library called "my_lib" with some files in it
+library my_lib some_file.sv all/in/dir/*.sv other/file2.sv
+@endcode
+
+All files specified in a library map are loaded and parsed as if they had
+been passed using the `-v` flag.
+
+@section library-search Searching for Library Files
+
+slang can also dynamically search for library files instead of needing them
+provided up front, assuming they are named in a predictable fashion. This is
+accomplished by using the `--libdir` flag to specify directories in which to
+search for library modules, and `--libext` to specify which file extensions
+these module files will have (.v and .sv are included by default).
+
+After parsing all explicitly provided sources, slang will look through all
+module instantiations, package import directives, and interface port declarations
+and build a set of names that are not satisfied by any modules, packages,
+or interfaces already in the design. Then it will search in each provided
+`--libdir` directory for a file with the name of the missing module/interface/package
+and one of the provided extensions. If found, it will load that file as a
+library file and include it in the build. This process continues until all
+missing names are satisfied or all file names have been searched.
 
 @section command-files Command Files
 
@@ -98,6 +165,15 @@ like any other form of whitespace. Some important features are as follows:
 -  Arguments set in a command file are overridden by anything set on the command line if they would
    otherwise conflict.
 
+@section built-in-macros Built-in Macros
+
+There are a handful of slang-specific predefined macros that you can reference in your code:
+Name | Value
+---- | -----
+\`__slang__ | 1
+\`__slang_major__ | *slang major version number*
+\`__slang_minor__ | *slang minor version number*
+
 @section system-funcs Nonstandard Built-in Functions
 
 Besides the system tasks and functions specified in the SystemVerilog LRM, slang also provides

include/slang/driver/Driver.h

@@ -37,17 +37,19 @@ namespace slang::driver {
 /// that could otherwise be used on their own.
 ///
 /// A typical compilation flow using the driver looks as follows:
+///
 /// @code{.cpp}
 /// Driver driver;
 /// driver.addStandardArgs();
-/// if (!driver.parseCommandLine(someStr)) { /* error */ }
-/// if (!driver.processOptions()) { /* error */ }
-/// if (!driver.parseAllSources()) { /* error */ }
+/// if (!driver.parseCommandLine(someStr)) { ...error }
+/// if (!driver.processOptions()) { ...error }
+/// if (!driver.parseAllSources()) { ...error }
 ///
 /// auto compilation = driver.createCompilation();
-/// if (!driver.reportCompilation(*compilation)) { /* error */ }
-/// else { /* success */ }
+/// if (!driver.reportCompilation(*compilation)) { ...error }
+/// else { ...success }
 /// @endcode
+///
 class SLANG_EXPORT Driver {
 public:
     /// The command line object that will be used to parse
@@ -255,7 +257,7 @@ class SLANG_EXPORT Driver {
     /// @brief Processes the given command file(s) for more options.
     ///
     /// Any errors encountered will be printed to stderr.
-    /// @param fileName The name (and potentially the path) of the command file to process.
+    /// @param pattern a file path pattern indicating the command file(s) to process.
     /// @param makeRelative indicates whether paths in the file are relative to the file
     ///                     itself or to the current working directory.
     /// @returns true on success and false if errors were encountered.