[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections |
Date: |
Sat, 22 Jun 2024 10:48:47 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) |
John Snow <jsnow@redhat.com> writes:
> On Fri, Jun 21, 2024 at 2:38 AM Markus Armbruster <armbru@redhat.com> wrote:
[...]
>> I'd like you to express more clearly that you're talking about an
>> alternative you rejected. Perhaps like this:
>>
>> block-level constructs such as code blocks, lists, and other such
>> markup.
>>
>> The alternative would be to somehow undo .get_doc_indented()'s
>> indentation changes in the new generator. Much messier.
>>
>> Feel free to add more detail to the last paragraph.
>>
>
> Eh, I just deleted it. I recall running into troubles but I can't
> articulate the precise conditions because as you point out, it's a doomed
> strategy for other reasons - you can't reconstruct the proper indentation.
>
> This patch is still the correct way to go, so I don't have to explain my
> failures at length in the commit message ... I just like giving people
> clues for *why* I decided to implement things a certain way, because I
> often find that more instructive than the "how".
"Why" tends to be much more useful in a commit message than "how". I
should be able to figure out "how" by reading the patch, whereas for
"why", I may have to read the author's mind.
> In this case, the "why" is
> probably more properly summarized as "it's a total shitshow in that
> direction, trust me"
The right amount of detail is often not obvious. Use your judgement.
- [PATCH 03/13] docs/qapidoc: delint a tiny portion of the module, (continued)
- [PATCH 03/13] docs/qapidoc: delint a tiny portion of the module, John Snow, 2024/06/18
- [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/18
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, Markus Armbruster, 2024/06/19
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/20
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, Markus Armbruster, 2024/06/20
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/20
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, Markus Armbruster, 2024/06/21
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/21
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections,
Markus Armbruster <=
[PATCH 05/13] qapi/parser: fix comment parsing immediately following a doc block, John Snow, 2024/06/18
[PATCH 06/13] docs/qapidoc: fix nested parsing under untagged sections, John Snow, 2024/06/18
[PATCH 07/13] qapi: fix non-compliant JSON examples, John Snow, 2024/06/18
[PATCH 08/13] qapi: ensure all errors sections are uniformly typset, John Snow, 2024/06/18
[PATCH 10/13] qapi: update prose in note blocks, John Snow, 2024/06/18