Reformat remarks for boolean properties to take advantage of XML definition lists

[cjsha]

Refer to this issue in the docs repo to understand what this issue proposes to accomplish.

Supposing that we all agree with this issue's goal, the remarks for all boolean properties should be reformatted into XML definition lists.

The commit that closes this issue should only be merged into main after the docs template has custom html/css for XML definition lists (basically only after the aforementioned issue closes).

[jonnew]

This is a nice idea. Can you propose and exact example syntax for the XML comment on a boolean property to get what you need?

[cjsha]

        /// <remarks>
        /// <list type="table">
        /// <item>
        /// <term> True </term> 
        /// <description> A <see cref="Bno055Data"/> instance that shares a <c>DeviceName</c> will produce data </description>
        /// </item>
        /// <item>
        /// <term> False </term> 
        /// <description> A <see cref="Bno055Data"/> instance that shares a <c>DeviceName</c> won't produce data. </description>
        /// </item>
        /// </list>
        /// </remarks>

would yield

DeviceName contains a space in the screenshot but it shouldn't. We don't use them at all, but those <c></c> tags are valid XML comment tags as well.

[jonnew]

I think the result is more confusing than just writing the sentence to be honest

…

On Tue, Aug 20, 2024, 1:01 PM cjsha ***@***.***> wrote: /// <remarks> /// <list type="table"> /// <item> /// <term> True </term> /// <description> A <see cref="Bno055Data"/> instance that shares a <c>DeviceName</c> will produce data </description> /// </item> /// <item> /// <term> False </term> /// <description> A <see cref="Bno055Data"/> instance that shares a <c>DeviceName</c> won't produce data. </description> /// </item> /// </list> /// </remarks> would yield image.png (view on web) <https://github.com/user-attachments/assets/000d292a-6c2a-48c4-ab54-ad17462bdc33> DeviceName contains a space in the screenshot but it shouldn't. We don't use them at all, but those <c></c> tags are valid XML comment tags as well. — Reply to this email directly, view it on GitHub <#198 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAK47YY6I3XLNCTBWRXGHC3ZSNY7ZAVCNFSM6AAAAABMGVIEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOJZGMZTENRQGQ> . You are receiving this because you commented.Message ID: ***@***.***>

[cjsha]

If you look again at the original issue in the docs repo, do you feel the same way?

[jonnew]

No, i guess not. It does seem clearer with with bullets.

However, both of these docs have a problem which is that the Configuration node cannot say what data node to use because they are linked only through a device type. There could be different data nodes for the same configuration node. And with e.g. the TS4231xx stuff there are. So, this has nothing to do with the formatting of the boolean anymore but is a problem in both cases.

[cjsha]

ok I opened a separate issue for that.

If you think this is something we want to do (reformatting remarks), feel free to assign me and set a milestone.