Finish writing `QuantityPoint` reference #152

chiphogg · 2023-07-25T20:53:53Z

We take the Quantity reference as a template, and adjust the contents
accordingly.

Many sections can be omitted. For example, we don't support
multiplication or division, and there is no "corresponding quantity
point" machinery at this time.

Other concepts are unique to QuantityPoint. For example, addition and
subtraction always involve both QuantityPoint and Quantity. Also,
there are further restrictions on implicit conversions in the case of
units with offset origins that can't be represented as integers.

A few other docs got updated as well.

Fixed a typo in the Quantity reference.
Added a link anchor in the Unit reference.
Added a section on quantity point makers in the unit slots discussion.

To test this change, I clicked on every link and made sure it went where
I was expecting.

I also opened the Quantity and QuantityPoint reference docs in two
neighboring tabs, and clicked on every corresponding section one at a
time, tabbing back and forth to see the changes.

Fixes #140.

We take the `Quantity` reference as a template, and adjust the contents accordingly. Many sections can be omitted. For example, we don't support multiplication or division, and there is no "corresponding quantity point" machinery at this time. Other concepts are unique to `QuantityPoint`. For example, addition and subtraction always involve both `QuantityPoint` and `Quantity`. Also, there are further restrictions on implicit conversions in the case of units with offset origins that can't be represented as integers. A few other docs got updated as well. - Fixed a typo in the `Quantity` reference. - Added a link anchor in the `Unit` reference. - Added a section on quantity point makers in the unit slots discussion. To test this change, I clicked on every link and made sure it went where I was expecting. I also opened the `Quantity` and `QuantityPoint` reference docs in two neighboring tabs, and clicked on every corresponding section one at a time, tabbing back and forth to see the changes. Fixes #140.

Punctuation change -- semicolon to colon

Updated heading caps to sentence case

johnzoppina

Chip,

I had a couple questions/thoughts for you, especially on the quantity_point file. Take a look and see if these things I've brought up make sense -- if you decide no changes are necessary, let me know and I'll approve.

John

johnzoppina · 2023-07-31T17:28:20Z

docs/reference/quantity_point.md

+### Quantity Point Maker (preferred)
+
+The preferred way to construct a `QuantityPoint` of a given unit is to use the _quantity point
+maker_ for that unit.  This is a callable whose name is the plural form of that unit, expressed in


Is "callable" a noun, or an adjective in an unfinished phrase (e.g. a callable [something])

Thanks for asking. I intended it to be a noun, which I think is a common choice.

johnzoppina · 2023-08-02T18:24:47Z

docs/reference/quantity_point.md

+```
+
+However, the _preferred_ way to construct a `QuantityPoint` is actually neither of these.  It's the
+_quantity point maker_, which we describe next.


It's pretty confusing to introduce this concept by saying "There are two ways to construct a QuantityPoint object (...description of ways...) but it's preferable not to use either one." -- the code block takes up a lot of space to demonstrate something that maybe shouldn't be the reader's first course of action.

So, notes:

What do we accomplish by discussing these sub-ideal alternatives in such detail? Is it that the information is expected, or do either of these accomplish something unique that Quantity Point Maker doesn't/can't?

If these are necessary, is it possible to place them in a show/hide or an expand section, maybe something like:

Alternatives to Quantity Point Maker (header)

Implicit Constructor from another QuantityPoint

Default constructor

It's a little confusing that "Default constructor" is how we describe something that's not preferred. Is this a matter of convention, or have we assigned it that name/title/designation?

Great callout, thanks. The reason this section reads as it does is because I copied it from the Quantity doc and modified it. I've cleaned it up here, and also made similar improvements in the quantity doc. Specific cleanups include:

Stating clearly up front that we prefer the quantity (point) makers.

Splitting out the constructor signature expositions into their respective sections.

As for "default constructor", yes, that is the C++ term of art for a constructor that takes no arguments, and we don't expect our target users to find this confusing.

johnzoppina · 2023-08-02T18:29:48Z

docs/reference/quantity_point.md

+the unit at the callsite.  There are two functions which can do this, depending on whether you want
+to access by value or by reference.
+
+### `.in(unit)` {#extracting-with-in}


in the previous paragraph, you mention that the chosen function depends on whether the reader wants to access by value or by reference -- but the headers that follow make no mention of value or reference, that's left to the text.

Is it possible to place value or reference in the header instead? (I know that this information is in the first sentence following those headers and understand why this looks like a minor quibble, but it does help these sections to better parallel the introduction)

Done: here, and in the quantity doc.

johnzoppina · 2023-08-02T19:05:01Z

docs/reference/quantity_point.md

+
+??? example "Example: forcing a conversion from centimeters to meters"
+    `centi(meters_pt)(200).as(meters_pt)` is not allowed.  This conversion will divide the
+    underlying value, `200`, by `100`.  While this particular value would produce an integer result,


Can we use an example that wouldn't divide into an integer result evenly -- perhaps 250 cm as m? Using example values that would produce a valid int result doesn't emphasize your point as strongly.

I actually wanted a result that divides evenly! I expect human readers to notice that these specific numbers would work, but I wanted to remind them that the compiler can't know the actual number when it makes the permit/forbid decision, as the program is being built. Note that the third paragraph drives the point home by showing what would happen if we forced the conversion with an inexact multiple.

That said, I think the wording here could be much better, so I cleaned it up. I made my emphasis more explicit, and I combined the second and third paragraphs because they're both about forcing.

chiphogg

Thanks for the great review! I like it much better after addressing your comments.

chiphogg · 2023-08-05T15:24:18Z

docs/reference/quantity_point.md

+### Quantity Point Maker (preferred)
+
+The preferred way to construct a `QuantityPoint` of a given unit is to use the _quantity point
+maker_ for that unit.  This is a callable whose name is the plural form of that unit, expressed in


Thanks for asking. I intended it to be a noun, which I think is a common choice.

chiphogg · 2023-08-05T15:36:24Z

docs/reference/quantity_point.md

+```
+
+However, the _preferred_ way to construct a `QuantityPoint` is actually neither of these.  It's the
+_quantity point maker_, which we describe next.


Great callout, thanks. The reason this section reads as it does is because I copied it from the Quantity doc and modified it. I've cleaned it up here, and also made similar improvements in the quantity doc. Specific cleanups include:

Stating clearly up front that we prefer the quantity (point) makers.

Splitting out the constructor signature expositions into their respective sections.

As for "default constructor", yes, that is the C++ term of art for a constructor that takes no arguments, and we don't expect our target users to find this confusing.

chiphogg · 2023-08-05T15:37:57Z

docs/reference/quantity_point.md

+the unit at the callsite.  There are two functions which can do this, depending on whether you want
+to access by value or by reference.
+
+### `.in(unit)` {#extracting-with-in}


Done: here, and in the quantity doc.

chiphogg · 2023-08-05T15:47:52Z

docs/reference/quantity_point.md

+
+??? example "Example: forcing a conversion from centimeters to meters"
+    `centi(meters_pt)(200).as(meters_pt)` is not allowed.  This conversion will divide the
+    underlying value, `200`, by `100`.  While this particular value would produce an integer result,


I actually wanted a result that divides evenly! I expect human readers to notice that these specific numbers would work, but I wanted to remind them that the compiler can't know the actual number when it makes the permit/forbid decision, as the program is being built. Note that the third paragraph drives the point home by showing what would happen if we forced the conversion with an inexact multiple.

That said, I think the wording here could be much better, so I cleaned it up. I made my emphasis more explicit, and I combined the second and third paragraphs because they're both about forcing.

johnzoppina

This looks good to me.

chiphogg added the release notes: 📝 documentation PR affecting library documentation label Jul 25, 2023

chiphogg requested review from tobin and johnzoppina July 25, 2023 20:53

johnzoppina added 2 commits July 31, 2023 12:06

Update unit-slots.md

b61e776

Punctuation change -- semicolon to colon

Update quantity_point.md

8aa338c

Updated heading caps to sentence case

johnzoppina suggested changes Aug 2, 2023

View reviewed changes

chiphogg added 2 commits August 5, 2023 11:49

Merge branch 'main' into quantity-point#140

a0c3a26

Respond to review feedback

8a8dd92

chiphogg commented Aug 5, 2023

View reviewed changes

chiphogg requested a review from johnzoppina August 5, 2023 15:54

johnzoppina approved these changes Aug 7, 2023

View reviewed changes

tobin approved these changes Aug 28, 2023

View reviewed changes

Merge branch 'main' into quantity-point#140

7618738

chiphogg merged commit 0a169b9 into main Aug 29, 2023
9 checks passed

chiphogg deleted the quantity-point#140 branch August 29, 2023 01:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Finish writing `QuantityPoint` reference #152

Finish writing `QuantityPoint` reference #152

chiphogg commented Jul 25, 2023

johnzoppina left a comment

johnzoppina Jul 31, 2023

chiphogg Aug 5, 2023

johnzoppina Aug 2, 2023

chiphogg Aug 5, 2023

johnzoppina Aug 2, 2023

chiphogg Aug 5, 2023

johnzoppina Aug 2, 2023

chiphogg Aug 5, 2023

chiphogg left a comment

chiphogg Aug 5, 2023

chiphogg Aug 5, 2023

chiphogg Aug 5, 2023

chiphogg Aug 5, 2023

johnzoppina left a comment

Finish writing QuantityPoint reference #152

Finish writing QuantityPoint reference #152

Conversation

chiphogg commented Jul 25, 2023

johnzoppina left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chiphogg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnzoppina left a comment

Choose a reason for hiding this comment

Finish writing `QuantityPoint` reference #152

Finish writing `QuantityPoint` reference #152