Dear list,
Currently, I'm trying to convert object-oriented documentation as DocBook (specifically, a C++ library, Qt). The pages with linear content are no problem (such as http://doc.qt.io/qt-5/qtbluetooth-heartlistener-example.html), but I'm ill-at-ease when it comes to class documentation, such as http://doc.qt.io/qt-5/qlowenergycharacteristic.html. My first idea was to create an <article> for each class, with a first section Detailed Description, then another one Member Function Documentation (mapping the structure of the original documentation); avoiding those sections would even be better, as they add no semantics to the document. This second section would have contained a <classsynopsis> with all the methods in <methodsynopsis> and their documentation (i.e. a set of paragraphs for each method). However, a <methodsynopsis> does not allow textual content as <para>. <?xml version="1.0" encoding="UTF-8"?> <db:article xmlns:db="http://docbook.org/ns/docbook"; xmlns:xlink=" http://www.w3.org/1999/xlink"; version="5.0"> <db:info> <db:title>QLowEnergyCharacteristic</db:title> </db:info> <db:section> <db:title>Detailed Description</db:title> <db:para>The <db:link xlink:href="qlowenergycharacteristic.html" >QLowEnergyCharacteristic</db:link> class stores information about a Bluetooth Low Energy service characteristic.</db:para> <!-- ... --> </db:section> <db:section> <db:title>Member Function Documentation</db:title> <db:classsynopsis> <db:ooclass> <db:classname>QLowEnergyCharacteristic</db:classname> </db:ooclass> <db:constructorsynopsis xml:id="QLowEnergyCharacteristic"> <db:para>Construct a new QLowEnergyCharacteristic. A default-constructed instance of this class is always invalid.</db:para> </db:constructorsynopsis> <db:constructorsynopsis xml:id="QLowEnergyCharacteristic-2"> <db:methodparam> <db:modifier>const</db:modifier> <db:type>QLowEnergyCharacteristic &</db:type> <db:parameter>other</db:parameter> </db:methodparam> <db:para>Construct a new QLowEnergyCharacteristic that is a copy of other.</db:para> </db:constructorsynopsis> <!-- ... --> </db:classsynopsis> </db:section> </db:article> Few examples exist for class documentations; the only one I was able to find is https://raw.githubusercontent.com/mfuchs23/dbdoclet/39fdff549d4477cdaf29a12c3712411fbff0a489/org.dbdoclet.doclet.docbook/doc/Reference.xml. It uses one section per class, starting with a <classsynopsis>, then nested sections afterwards for the methods if there is anything to say about them. This way of doing things makes me feel dubious, as there is no direct link between the class and its method: each method basically copies a part of the class definition. In my case, as all methods have a few words about them, there is a high risk of someone changing (inadvertently) a letter or anything (<classsynopsis> could even be avoided); and at the semantic level, the notion of class or method documentation would be completely lost (as the real documentation would just be a set of sections). Going to the Definitive Guide for DocBook 5.1, <refentry> seems to be preferred, but it's roughly the same idea. How would you do it? What's the best way of using the current mark-up? (Ideally, I'd rather avoid customisation to have a standard content model, but I'm not against using a prerelease version.) A follow-up question is the handling of C and C++'s enum (equivalent to an integer type, where values can have names). I don't think there is anything suited for these cases in DocBook yet. https://github.com/mfuchs23/dbdoclet/blob/39fdff549d4477cdaf29a12c3712411fbff0a489/org.dbdoclet.doclet.docbook/doc/Reference.xml#L1634 uses a series of public fields for Java enumerations, but that makes no sense for C++. For example, I'd like to convert the enumeration http://doc.qt.io/qt-5/qlowenergycharacteristic.html#PropertyType-enum. I would think about something like this: <db:enumsynopsis> <db:enumname>QLowEnergyCharacteristic::PropertyType</db:enumname> <db:enumvalue> <db:litteral type="constant">QLowEnergyCharacteristic::Unknown</db:litteral> <db:litteral type="int">0x00</db:litteral> <db:para>The type is not known.</db:para> </db:enumvalue> </db:enumsynopsis> Is there anything that I've missed about this? Thanks in advance for your thoughts! Thibaut Cuvelier
