Anthony Liguori <anth...@codemonkey.ws> writes: > On 05/12/2011 11:08 AM, Markus Armbruster wrote: >> Anthony Liguori<anth...@codemonkey.ws> writes: >> >>> On 05/12/2011 10:25 AM, Gerd Hoffmann wrote: >>>> Hi, >>>> >>>>>> What is the status of the qdev documentation patches btw.? >>>>> >>>>> http://lists.gnu.org/archive/html/qemu-devel/2011-02/msg02169.html >>>> >>>> What is the problem with the empty strings btw? >>>> >>>> The only way around I can see is having _DOC and _NODOC versions for all >>>> the property macros, but I'd prefer to not have _NODOC macros in the >>>> tree ... >>> >>> Inline documentation is bad. Our documentation should be >>> centralized. That's the only way to keep it consistent and thorough. >> >> External documentation of code details is bad. Our documentation should >> be next to the code. That's the only way to keep it up-to-date and >> consistent with the code. > > qdev properties are *not* code details. It's a public user interface > that we have to support for every.
The fact that they are public user interface doesn't change the fact that they're code at all. They are *both*. > It should be disconnected from the internal implementation. And yes, > the incestuous relationship that exists today is a problem, but it's > one we're going to have to live with. I doubt we'll ever reach consensus on this one. >>> There's no way to easily extract the inline docs in a complete way >>> since some devices are built conditionally. >> >> For each configured target: extract docs of the devices it builds >> Concatenate and discard the duplicates >> >> Yes, that means you don't get docs for devices none of your targets has. >> That's a feature. If you really want docs for all devices, build all >> targets. > > But for things like Spice where the lack of libspice influences > whether the device is available, how do I extract formal documentation > to publish on qemu.org reliably? If no maintainer of QEMU can build with Spice enabled, it got more serious problems than extracting its documentation.
