Skip to content

Conversation

@chiphogg
Copy link
Member

Some users have found some aspects of these docs confusing. This PR
fixes them up to make the guide easier to use. Here are the problems
and how we handled them.

  • Problem: It was unclear which namespace should contain the
    definitions of new units.

    • Solution: Append , in your project's namespace to the
      comments in the guide.
  • Problem: It was unclear which namespace the symbols namespace
    should go in.

    • Solution: The above change should automatically clarify this
      as well.
  • Problem: The au:: namespace was omitted from Au library
    constructs, making it unclear whether we had elided a using clause,
    or whether we wanted users to define the units in the au namespace.

    • Solution: The desired namespace should no longer be unclear.
      We had been writing the docs by omitting the au namespace to
      reduce visual clutter, but this is less appropriate for a how-to
      guide. We have added the namespace.

Of course, this last point applies with equal force to every other
how-to guide. It's OK to eliminate the au:: namespace qualifier in
the text, but we should keep the code samples as usable as possible.
Therefore, we apply this approach more consistently.

Fixes #504.

Some users have found some aspects of these docs confusing.  This PR
fixes them up to make the guide easier to use.  Here are the problems
and how we handled them.

- **Problem:** It was unclear which namespace should contain the
  definitions of new units.
    - **Solution:** Append `, in your project's namespace` to the
      comments in the guide.

- **Problem:** It was unclear which namespace the `symbols` namespace
  should go in.
    - **Solution:** The above change should automatically clarify this
      as well.

- **Problem:** The `au::` namespace was omitted from Au library
  constructs, making it unclear whether we had elided a `using` clause,
  or whether we wanted users to define the units in the `au` namespace.
    - **Solution:** The desired namespace should no longer be unclear.
      We had been writing the docs by omitting the `au` namespace to
      reduce visual clutter, but this is less appropriate for a how-to
      guide.  We have added the namespace.

Of course, this last point applies with equal force to every other
how-to guide.  It's OK to eliminate the `au::` namespace qualifier in
the _text_, but we should keep the _code samples_ as usable as possible.
Therefore, we apply this approach more consistently.

Fixes #504.
Just a little cleaner.
@chiphogg chiphogg requested a review from Copilot August 16, 2025 20:21
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR clarifies the documentation for creating new units in Au by addressing namespace ambiguity and improving code sample usability. The changes ensure users understand where to define units and provide complete, runnable code examples.

  • Added au:: namespace qualifiers to all code samples for clarity
  • Clarified that new units should be defined in the user's project namespace
  • Made code samples more self-contained and usable

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file
File Description
docs/howto/new-units.md Added namespace clarifications and au:: qualifiers to unit definition examples
docs/howto/quantity-template-parameters.md Added au:: qualifiers to template parameter examples
docs/howto/new-dimensions.md Added au:: qualifiers to dimension and unit creation examples
docs/howto/new-constants.md Added namespace clarifications and au:: qualifiers to constant creation examples
docs/howto/forward-declarations.md Added explanatory note about namespace usage and au:: qualifiers to code samples

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@chiphogg chiphogg merged commit 5418588 into main Aug 17, 2025
14 checks passed
@chiphogg chiphogg deleted the chiphogg/new-units#504 branch August 17, 2025 02:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Question: namespace for new (custom) units

3 participants