Address #7491 - Configuration of pointer/ref placement in C++ decls

[vector-of-bool]

Subject: Allow configuration of the placement of the reference and pointer tokens in C++ declarations in the rendered output.

Feature or Bugfix

• Feature - 2 additional configuration options, no changes for existing projects

Purpose

• This change adds options cpp_ptr_placement and cpp_ref_placement, which determine where the rendered output will attach the reference & or pointer * declaration token relative to the main type and the declared name. "right" (the current behavior and default) will attach towards the right on the declared name, whereas "left" will attach towrads the left, closer to the pointed-to/referred type.

Relates

• C++domain: Idiomatic spacing of ptr-operator and ref-qualifier #7491

[jbab]

Thanks so much, I really appreciate this.

From a quick glance and a smoke test on my personal, very rudimentary C++-docs-with-sphinx attempts, results look good, except for one thing: I would expect the ampersand in a function ref-qualifier to be attached to the const (or volatile) in the left mode: int f() const&, not int f() const &.

As for the names of the options, I like them, they are neutral and convey their meaning. Also specifying the option value as an enum is a plus; in this way future extension are possible, e.g. a value "middle".

Having said that I am still a little concerned about the many output variations this results in and the impact this has on testing and maintenance. The crucial question is what is really needed. There must be a reason that another widely-used tool, clang-format, fares well with only one option (and three values): PointerAlignment.

[vector-of-bool]

I thought about reducing it to a single option for both, and maybe that's a good idea. I don't know of any codebases that mix-and-match the alignment of their * and & tokens. There's no compelling reason they can't be consolidated to a single option.

I didn't consider the case with ref-qualified functions. I'll look into that one.

[eric-wieser]

Marginally faster as

Suggested change

	if val not in ('left', 'right'):
	raise RuntimeError('Invalid C++ placement parmeter value '
	'"{}", should be either "left" or "right"'.format(val))
	return _Placement(val)
	try:
	return _Placement(val)
	except ValueError:
	raise RuntimeError('Invalid C++ placement parmeter value '
	'"{}", should be either "left" or "right"'.format(val)) from None