Header structure
Ordinary headers include the prerequisites for their own declarations. Callers should not need an undocumented sequence of includes.
Header |
Role |
|---|---|
|
Installed entry points with no Tk dependency. |
|
Generated companion included through |
|
Shared padding, geometry and dash records. |
|
Common and platform-specific resource defaults. |
|
Text declarations using shared types, without including |
|
Common graph definitions; track records and services respectively. |
|
Component-facing private rendering contracts. |
|
Backend context prefix and operation tables. |
|
Native services with opaque platform resources. |
Use forward declarations for pointer-only dependencies and the defining header for embedded records. Define each type once. Include guards make repeated inclusion safe; reciprocal includes do not solve dependency cycles.
Only include the applicable platform configuration. rbcWin.h is Windows-only. Pixel channels use explicit members
such as pixel.rgba.red; generic macros named Red or Blue would alter later SDK declarations.
Run make test-headers after dependency changes. Its compile-only probes cover standalone, repeated, forward/reverse
and graph-relative inclusion, public-header Tk isolation, and image/default-name regressions. Run them on both
platforms and with both Cairo configurations. These checks complement runtime tests; they do not establish ABI
compatibility.
Record coverage
The C references include member descriptions for the reviewed header records and their component-owned implementation
records. Start with Axis, Axis2D, RbcTrack, Line, MarkerStruct,
TextStyle and Rbc_Vector_s. Shared geometry such as Point2D, Region2D and
Rbc_Dashes is documented in Geometry C reference.
Windows-only fields and packed file headers are extracted separately in Windows native backend C reference. Generated stubs
are ABI dispatch tables, not component state; regenerate them from the declarations rather than editing rbcDecls.h
to add handwritten field contracts. Function-local scratch records and disabled compatibility branches are not
standalone API records.
A field description belongs at its declaration. Use a separate declaration for each member when their contracts differ: Doxygen associates a trailing comment on a grouped declaration only with the last member. A record in XML must also be rendered with members in its component reference; extraction alone does not provide a navigable member contract in the manual.