Skip to content
This repository was archived by the owner on Aug 12, 2026. It is now read-only.
This repository was archived by the owner on Aug 12, 2026. It is now read-only.

Define and normalize the public C++ namespace and API boundary #115

Closed

Description

@acgetchell

Summary

Define and normalize CDT++'s supported C++ namespace and public API boundary before the final v1.0.0 archival release.

The current headers mix global declarations, several unrelated top-level namespaces, a newer cdt root namespace, and implementation helpers that are inconsistently placed in detail. The code is valid C++23, but callers and Doxygen cannot reliably distinguish supported API from cross-header or implementation-only machinery.

This is an API-contract audit, not a mechanical namespace-style rewrite. Every declaration must be classified before it is moved, retained, deprecated, or documented.

Current evidence

  • Random.hpp uses the cdt root namespace, while other components use top-level namespaces such as manifolds, ergodic_moves, foliated_triangulations, utilities, runtime_config, move_tracker, s3_action, and mpfr_values.
  • Several public headers expose aliases, constants, enums, templates, classes, and functions directly in the global namespace, including Settings.hpp, Foliated_triangulation.hpp, Geometry.hpp, the move-strategy headers, and part of S3Action.hpp.
  • ergodic_moves::detail is correctly used for some helpers, but analogous helpers remain in ergodic_moves, including do_26_move_impl, cavity-recognition helpers, collection helpers, and low-level retriangulation operations.
  • incident_cells_from_edge and get_incident_cells expose overlapping behavior.
  • Tests call several low-level helpers directly, but test access alone does not establish a supported caller contract.
  • fmt formatter specializations intentionally belong in the external library's customization namespace and must not be moved into the project namespace.

Scope

Inventory and classification

  • Inventory declarations in every header under include/.
  • Classify each as supported public API, supported customization point, cross-header internal API, implementation detail, or legacy/experimental surface.
  • Record representative production consumers, tests, and any documented external call sites before changing a declaration.
  • Establish the intended source-compatibility and binary-compatibility policy for this final header-heavy C++ release; do not infer a stable ABI merely from build options.

Namespace policy

  • Decide whether cdt is the project root namespace and define coherent component subnamespaces.
  • Eliminate unintended global-namespace declarations from public headers, preserving only explicitly justified language- or library-required customization points.
  • Use detail consistently for implementation-only names while recognizing that it is a convention rather than access control.
  • Keep anonymous namespaces out of public headers; translation-unit-local anonymous namespaces remain valid in source and test files.
  • Avoid namespace-wide using directives in public headers.
  • Decide whether compatibility aliases or deprecation shims are appropriate for renamed public names, and give any retained compatibility surface an explicit removal/archive policy.

Ergodic-move boundary

  • Keep the high-level null_move, do_*_move, and propose_*_move operations public unless caller evidence supports a different contract.
  • Move clearly internal implementation functions such as do_26_move_impl and cavity/collection helpers into detail or an implementation header.
  • Decide explicitly whether try_23_move, try_32_move, try_62_move, and bistellar_flip are supported advanced APIs or internal mutation machinery.
  • Decide explicitly whether check_move is a supported diagnostic API or an internal postcondition used across headers.
  • Remove or consolidate redundant helper surfaces such as incident_cells_from_edge and get_incident_cells.
  • Update tests so black-box move correctness does not depend on implementation-only helpers; retain focused white-box tests only where they protect a deliberately internal contract.

Validation and documentation coupling

  • Add minimal external-consumer compile tests that include only supported headers and use only the intended public namespace surface.
  • Add compile-time checks for important public signatures, concepts, result types, and ownership/value-category contracts where useful.
  • Configure generated API documentation to present the supported surface clearly and exclude or visibly classify detail names.
  • Coordinate the resulting public surface with Validate and finalize the archival documentation site #114 before enabling strict Doxygen completeness warnings.

Acceptance criteria

  • Every declaration under include/ has an intentional API classification.
  • The repository has a documented root-namespace and detail policy with explicit exceptions.
  • Public headers introduce no unintended project-owned names into the global namespace.
  • Similar internal helpers are treated consistently; is_32_movable is not an isolated exception while analogous cavity-recognition helpers remain accidentally public.
  • Low-level ergodic-move operations and check_move have explicit supported-or-internal decisions backed by real caller requirements.
  • Redundant namespace-level helper APIs are consolidated or justified.
  • Required source-compatibility shims are documented and tested; unnecessary compatibility aliases are not retained indefinitely.
  • Minimal external-consumer tests compile using only the supported API, while the full C++ test suite remains green.
  • Doxygen can distinguish the supported public surface from implementation details and Validate and finalize the archival documentation site #114 can enforce documentation completeness at that boundary.
  • No scientific move semantics, numerical formulas, or unrelated architecture are changed merely to reorganize names.

Boundaries and relationships

Prefer the smallest coherent v1.0.0 surface. Do not add namespaces, aliases, abstraction layers, or versioning machinery without a concrete caller or archival-maintenance benefit.

Activity

  1. added this to the v1.0.0 milestone on Jul 21, 2026
  2. added a commit that references this issue on Jul 27, 2026
    a02a732
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions