QtDoc: Formatting of code blocks following `\value` tables in Qml property docs

FeRDNYC

I noticed that, in a particular page of the Qt documentation itself (the QtQuick Text Input doc), both the docs.qt.io site and the QtAssistant rendering are showing the same formatting issue.

\qml code blocks format fine elsewhere, but whenever one immediately follows the \value list of a \qmlproperty documentation comment, it ends up getting swallowed into the last cell in the second column of the values table.

On the website:

In QtAssistant:

...Looks bad, right? (Especially on the web, where the site template currently allows those <PRE> code blocks to blow out the document width like crazy.) And that's not the only instance, every \qmlproperty comment where a \qml block follows the \value list seems to be affected the same way. So, I'd like to fix that.

Except... I'm not sure how. The \qml block is already set off from the \value list, in fact there's even a blank line between the last \value and the \qml block opener. Here's the existing source for that same table:


/*!
    \qmlproperty int QtQuick::TextInput::font.weight

    The requested weight of the font. The weight requested must be an integer
    between 1 and 1000, or one of the predefined values:

    \value Font.Thin        100
    \value Font.ExtraLight  200
    \value Font.Light       300
    \value Font.Normal      400 (default)
    \value Font.Medium      500
    \value Font.DemiBold    600
    \value Font.Bold        700
    \value Font.ExtraBold   800
    \value Font.Black       900

    \qml
    TextInput { text: "Hello"; font.weight: Font.DemiBold }
    \endqml
*/

...I'm not sure how much more separated they can be, it's surprising that the formatting is going wrong the way it is.

Does anyone have any ideas why the code block would end up being considered part of the \values table, or have any suggestions for the "Right Way™" to fix the source so that doesn't happen? I mean, I could try inserting a manual \br or an empty \span or \div, but that's already feeling really kludgey.

FeRDNYC

(This probably isn't the right category for this question, but I couldn't find a more appropriate-sounding one.)

SGaist

Hi,

I think you might have found an issue with qdoc. Did you already check the bug report system for something similar ?

FeRDNYC

@SGaist Somewhat, though it's not the easiest thing to search for.

The closest I've come is this closed issue which was actually about the opposite problem, where attempts to intentionally include \image embeds inside \value lists were breaking, because the \image was forcing a new paragraph. (The fix there was to switch to \inlineimage.)

\qml, it seems, does the opposite and refuses to begin a new paragraph, even when it's clearly separated from the preceding code by both vertical whitespace and indentation. It's kind of surprising that QtDoc seemingly doesn't consider those factors, in interpreting how to format documentation comments.

As a result, as @shawnrutledge said at the start of the conversation on that other bug,

I guess the trouble is you don't know when a \value should end.

Since that bug's closed, I guess I'll file this issue as a new one, though without significant changes to how QtDoc parses documentation comments (to add much more complex interpretation of indentation and line separations) I don't see that there's much to be done about this.

Maybe the right answer is to just insert some sort of manual break. Kludgey, but if it works...

FeRDNYC

(The code above maybe isn't the best illustration of QtDoc's frustrating refusal to interpret whitespace into block separators, but for example this code block is also swallowed into the last value, and if this doesn't end the \value block then I don't know what will.)

/*!
    \qmlproperty enumeration QtQuick::TextInput::font.capitalization

    Sets the capitalization for the text.

    \value Font.MixedCase       the normal case: no capitalization change is applied
    \value Font.AllUppercase    alters the text to be rendered in all uppercase type
    \value Font.AllLowercase    alters the text to be rendered in all lowercase type
    \value Font.SmallCaps       alters the text to be rendered in small-caps type
    \value Font.Capitalize      alters the text to be rendered with the first character of
                                each word as an uppercase character

    \qml
    TextInput { text: "Hello"; font.capitalization: Font.AllLowercase }
    \endqml
*/

FeRDNYC

Ooh, I should test whether \value is willing to take brace-wrapped arguments, like some other commands do:

/*!
      \qmlproperty enumeration Foo::Bar

      Bars the Foo.

      \value {Bar.Baz} {something something Qml something declarative.}
      \value {Bar.Faz} {blah blah...}

      \qml
      Foo { bar.baz: "Stuff"; }
      \endqml
*/

If that works, it could solve all these problems.

SGaist

Hope it does but I still think that a bug report is in order at least to update the documentation where it happens.

FeRDNYC

It didn't, anyway. (Sigh.)

The slightly weird thing is HOW it didn't work.

This code:

/*!
    \qmlproperty int QtQuick::TextInput::font.weight

    The requested weight of the font. The weight requested must be an integer
    between 1 and 1000, or one of the predefined values:

    \value {Font.Thin}    {100}
    \value {Font.ExtraLight}    {200}
    \value {Font.Light}    {300 and change}
    \value {Font.Normal}    {400 is the (default)}
    \value {Font.Medium}    {500}
    \value {Font.DemiBold}    {600}
    \value {Font.Bold}    {700}
    \value {Font.ExtraBold}    {800a}
    \value {Font.Black}    {900}

    \qml
    TextInput { text: "Hello"; font.weight: Font.DemiBold }
    \endqml
*/

Results in this:

But it wasn't even the \qml block. As an experimental control, I also did this:

    \value {TextInput.QtRendering} {Text is rendered using a scalable distance field for each glyph.}
    \value {TextInput.NativeRendering} {Text is rendered using a platform-specific technique.}
    \value {TextInput.CurveRendering} {Text is rendered using a curve rasterizer running directly on the graphics hardware. (Introduced in Qt 6.7.0.)}

And:

Apparently, \value takes an optionally { }-delimited first argument, followed by a free-text second argument with very impenetrable and magical rules for where it ends.

SGaist

I am going to sound like a broken record but: open a ticket.
You have enough material to warrant either a bug fix or a documentation fix.