Gaps between specification and implementation in typed_value::composing()

Start with src/variables_map.cpp in Boost 1.81.0, especially the first parsed-options loop at lines 48-93 and the xm.m_final update at line 102. Reproduce the single-store and repeated-store cases using the linked Wandbox examples, with and without composing(). Done means determining whether Example 63.2, its documentation, or the implementation is inconsistent and clearly documenting the conclusion.

Description and Reproduction

Consider Example 63.2 (Execution on Wandbox)

test --phone 123 --phone 456

In this case, both phone numbers, 123 and 456, are parsed. The call to composing() makes it possible to use a command-line option multiple times – the values are composed.

From this description, it would seem that, conversely, without the call to composing(), only 123 would be assigned to the --phone option but 456 would be ignored. (I assume this is the specification. Is my understanding correct?)

• It seems that there are others who have a similar understanding:
  • https://boost-users.boost.narkive.com/oyPRDQxi/program-options-documentation-dead-end#post2
  • https://stackoverflow.com/questions/8175723/vector-arguments-in-boost-program-options

However, even after removing composing(), both 123 and 456 are assigned to --phone. (Execution on Wandbox)

On the other hand, in order to confirm the effect of composing() in the current implementation, when store() is called twice, we can see that the result changes depending on whether composing() is called or not.

• Twice store() with composing(): Execution on Wandbox
• Twice store() without composing(): Execution on Wandbox

Implementation Analysis

From what I've seen of the implementation of Boost 1.81.0, these lines are suspect.

• In the first for loop to proceed the parsed options (L48-L93)
  • The condition for skipping assignment depends on xm.m_final. (L67-L68)
  • If is_composing() is false, new_final is modified. (L85-L91)
    • The comment here clearly states that composing() affects subsequent calls to store(). I think this statement has a gap with that in Example 63.2.
• After the first for loop, xm.m_final is modified by new_final (L102)

The intuitive image from the description of Example 63.2 is an implementation in which:

• Deleting L102.
• Modifying L91 to xm.m_final.insert(option_name)

Summary

• There seems to be a gap between the specification (which I can intuitively read from Example 63.2) and the implementation.
• I would like to clarify if my understanding is wrong or if either the description of Example 63.2 or implementation is incorrect.

Version

• Boost 1.81.0