Using the Reference
The API reference provides detailed documentation for Mach’s public API.
It is designed for looking up the exact behavior and interface of a class, function, method, type, or other API component while building with Mach.
Reference vs. Guides
Section titled “Reference vs. Guides”The main documentation and the API reference serve different purposes.
Use the guides when you want to learn how a Mach feature works or how different parts of the framework fit together. Use the API reference when you already know what you want to use and need precise information about it.
For example, if you want to learn how controllers work, start with the
Controllers guide. If you want to know exactly what methods are available on
mach::ControllerBase, look it up in the API reference.
The tutorial is best for learning Mach by building a complete application from start to finish.
Reading a Reference Page
Section titled “Reading a Reference Page”Reference pages document the public interface and behavior of an API as precisely as possible.
Depending on the API being documented, a page may include:
- The header required to use it.
- Its namespace and declaration.
- Constructors and member functions.
- Parameters and return values.
- Exceptions and error behavior.
- Usage notes and examples.
- Links to related APIs.
Not every section appears on every page. The reference includes the information that is relevant to the API being documented.
Headers and Namespaces
Section titled “Headers and Namespaces”Reference pages show the header that provides the documented API:
#include <mach/mach.hpp>APIs are shown using their fully qualified names, such as
mach::AppBuilder or mach::ControllerBase, so it is always clear which
namespace a type or function belongs to.
Some APIs may also be available through more specific convenience headers. Where relevant, the reference documents the appropriate header to include.
Declarations
Section titled “Declarations”Declarations show the public C++ interface as it appears to users of Mach.
For example:
mach::App build();Use the declaration to see the exact parameter types, return type, qualifiers, and other properties of the API.
Overloads are documented separately where their behavior or accepted arguments differ.
Examples
Section titled “Examples”Examples demonstrate typical usage of an API, but they are intentionally focused on the API being documented.
For larger examples that combine multiple Mach features, see the examples in the Mach repository.
Finding What You Need
Section titled “Finding What You Need”A useful rule of thumb is:
| If you want to… | Use |
|---|---|
| Learn a Mach feature | Guides |
| Build an application step by step | Tutorial |
| Look up a class, function, or method | API Reference |
| Check an exact signature or return type | API Reference |
| Understand how several APIs work together | Guides |
You can browse the reference using the sidebar or use the documentation search when you already know the name of the API you are looking for.