Re: [Qemu-devel] [PATCH v3 20/20] arm: add Faraday FTSPI020 SPI flash controller support

[Peter Maydell]

On 7 February 2013 12:13, Andreas Färber <address@hidden> wrote:
> Am 07.02.2013 13:04, schrieb Peter Maydell:
>> Do we really want to change the public/private boundaries of
>> our source code just for the benefit of the test framework? Ugh.
>
> The truth is (and that applies to the hw/ refactoring series as well)
> that we don't have a clear distinction between "public" and "private"
> headers for devices.

Yes. I would like it if we could create one :-)

The traditional qdev approach has been (IMHO) that there should be
no public header, because to instantiate and use a qdev device
you just need its name as a string. Conversion to qdev has often
allowed removal of public init functions etc that have been in
public-facing header files. QOM seems to want to make a little
more public (especially for abstract classes that will be
subclassed).

It's not clear to me if for QOM qdev devices we should now
be preferring qdev_create(NULL, TYPE_WOMBAT) to
qdev_create(NULL, "wombat") for straightforward non-abstract
device types.

I don't have a strong opinion on what we should do, but I would
like to see "QOM best practices" clearly documented so that
we can point people at it when they're implementing new devices
or converting existing ones, to gain some measure of consistency.

>> I would like it if we could define what we consider to be best
>> practice for public/private header files for QOM devices
>> (in particular whether we need a public header for every device
>> with the TYPE_ constants &c).
>
> gtk-doc for instance needs to scan one directory, so having all headers
> in include/ would be beneficial long-term - today we do not get
> generated documentation for qdev-core.h.

This is a bug in gtk-doc and should be fixed there if we care.
Also not all doc comments will be in header files; some are in .c
files, so you need to scan the whole source tree anyhow.

-- PMM