John Snow <js...@redhat.com> writes: > On Fri, Mar 28, 2025 at 4:36 AM Markus Armbruster <arm...@redhat.com> wrote: > >> John Snow <js...@redhat.com> writes: >> >> > Well, I tried. Maybe not very hard. Sorry! >> >> No need to be sorry! Kick-starting discussion with limited effort is >> better than a big effort going into a direction that turns out to be >> unwanted once we discuss it. >> >> Instead of just rephrasing Returns descriptions, I'd like us to consider >> both Returns and intro. See below for why.
[...] > I think for cases where the doc block is short and we have a desire to > merge "returns" and "intro", the intro makes the most sense if there isn't > anything of particular value assigned to the return value to begin with. > > So, more or less, yeah: if semantics are partially duplicated between > intro/returns, I'm in favor of putting it all in the intro and allowing > transmogrifier generate the return type info. > > I don't think there's a good case to make for a doc block with no intro but > a healthy paragraph in the returns section, that looks goofy. > > Of course: I think there are still circumstances where we'll want both the > intro and the returns info explicitly labeled, when we have some > information to document about the semantics of that return value. Agreed. [...]
