[hawkmoth] Re: [PATCH 05/13] hawkmoth: factor out documentation string generation
- From: Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
- To: hawkmoth@xxxxxxxxxxxxx, Jani Nikula <jani@xxxxxxxxxx>
- Date: Tue, 8 Jan 2019 23:24:29 +0100
On 1/8/19 10:17 PM, Jani Nikula wrote:
- cdom = '.. c:member:: {type}
{parent}{sep}{member}\n'.format(
The indentation does visually make the {parent}{sep} bit here redundant,
but the main purpose was to be able to reference distinct members of a
structure. Like :c:member:`name.membername`.
Given
struct foo {
int baz;
};
struct bar {
int baz;
};
it's impossible to reference baz unambiguously without documenting the
members as foo.baz and bar.baz.
Hm, I hadn't thought about that. I was going to argue against it as it
would be an incomplete and costly hack. However...
I have a stronger reason not to do it: Sphinx (I'm on 1.8.3) recognizes
the nesting automatically and does it for you. You can keep doing
:c:member:`name.membername`, it will work! :)
Keeping the old behaviour would actually break it when combined with the
nesting. I'm guessing you'd need c:member:`name.name.membername`.
You can still get to cases where you can't differentiate between them,
but there's 0 regressions relative to the old behaviour.
--
Bruno Santos
PGP KEY: 941052CD (pool.sks-keyservers.net)
Other related posts:
