If a macro has a string value, the @string attribute will contain the
value. Otherwise @string attribute will be missing.

For example, the following macro definition from libvirt-domain.h:

 /**
  * VIR_MIGRATE_PARAM_URI:
  * ...
  */
 # define VIR_MIGRATE_PARAM_URI               "migrate_uri"

will result in

 <macro name='VIR_MIGRATE_PARAM_URI' file='libvirt-domain' string='migrate_uri'>
   <info><![CDATA[...]]></info>
 </macro>

https://bugzilla.redhat.com/show_bug.cgi?id=1229199Signed-off-by: NJiri Denemark <jdenemar@redhat.com>

Signed-off-by: NJiri Denemark <jdenemar@redhat.com>

The apibuild.py script did not handle whitespace in preprocessor
macros, so it failed to detect constants declared with '# define'
instead of '#define'. Since we now correctly indent our public
header files, we have silently lost all constants from
libvirt-api.xml. This also caused us to not detect formatting
errors in constant docs

The API docs generators were broken by the header file
re-organization. Specifically

 * html/libvirt-libvirt.html was empty (and should be deleted)
 * Makefile.am didn't install html/libvirt-libvirt-*.html
 * hvsupport.html was mostly empty
 * sitemap.html.in didn't list the new html/*.html files

Create a new libvirt-host.h file to hold the public
API definitions for the virConnect type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-domain.h file to hold the public
API definitions for the virDomain type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-event.h file to hold the public
API definitions for the virEvent type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-storage.h file to hold the public
API definitions for the virStorage/Vol type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-stream.h file to hold the public
API definitions for the virStream type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Note the definition of virStreamPtr is not moved, since that
must be declared early for all other libvirt APIs to be able
to reference it.

Create a new libvirt-secret.h file to hold the public
API definitions for the virSecret type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-nodedev.h file to hold the public
API definitions for the virNodeDevice type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-nwfilter.h file to hold the public
API definitions for the virNWFilter type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-interface.h file to hold the public
API definitions for the virInterface type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-network.h file to hold the public
API definitions for the virNetwork type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Create a new libvirt-domain-snapshot.h file to hold the public
API definitions for the virDomainSnapshot type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Introduce a src/libvirt-host.c file to hold all the
methods related to the virConnect type.

Introduce a src/libvirt-domain.c file to hold all the
methods related to the virDomain type.

The virTypedParameterValidateSet method will need to be used
from several libvirt-*.c files so must be non-static
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

Introduce a src/libvirt-storage.c file to hold all the
methods related to the virStorage{Pool,Vol} types.

Introduce a src/libvirt-stream.c file to hold all the
methods related to the virStream type.

Introduce a src/libvirt-secret.c file to hold all the
methods related to the virSecret type.

Introduce a src/libvirt-nodedev.c file to hold all the
methods related to the virNodeDevice type.

Introduce a src/libvirt-nwfilter.c file to hold all the
methods related to the virNWFilter type.

Introduce a src/libvirt-interface.c file to hold all the
methods related to the virInterface type.

Introduce a src/libvirt-network.c file to hold all the
methods related to the virNetwork type.

Introduce a src/libvirt-domain-snapshot.c file to hold all the
methods related to the virDomainSnapshot type.

We publish libvirt-api.xml for others to use, and in fact, the
libvirt-python bindings use it to generate python constants that
correspond to our enum values.  However, we had an off-by-one bug
that any enum that relied on C's rules for implicit initialization
of the first enum member to 0 got listed in the xml as having a
value of 1 (and all later members of the enum were equally
botched).

The fix is simple - since we add one to the previous value when
encountering an enum without an initializer, the previous value
must start at -1 so that the first enum member is assigned 0.

The python generator code has had the off-by-one ever since DV
first wrote it years ago, but most of our public enums were immune
because they had an explicit = 0 initializer.  The only affected
enums are:
- virDomainEventGraphicsAddressType (such as
VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_IPV4), since commit 987e31ed
(libvirt v0.8.0)
- virDomainCoreDumpFormat (such as VIR_DOMAIN_CORE_DUMP_FORMAT_RAW),
since commit 9fbaff00 (libvirt v1.2.3)
- virIPAddrType (such as VIR_IP_ADDR_TYPE_IPV4), since commit
03e0e79e (not yet released)

Thanks to Nehal J Wani for reporting the problem on IRC, and
for helping me zero in on the culprit function.

* docs/apibuild.py (CParser.parseEnumBlock): Fix implicit enum
values.
Signed-off-by: NEric Blake <eblake@redhat.com>

Our documentation generator is a bit messy, to say the least. For
instance, the description to return values of a function is
searched within C comment. Currently, all lines that start with
'returns' or 'Returns' are viewed as return value description.
However, there are some valid uses where the 'returns' word is in
the middle of a sentence describing function behavior not the
return value. And there are no places where 'returns' is used to
describe return values.  For instance:
virDomainDetachDeviceFlags, virConnectNetworkEventRegisterAny and
virDomainGetDiskErrors. This leads to HTML documemtation being
generated incorrectly.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>

Any source file which calls the logging APIs now needs
to have a VIR_LOG_INIT("source.name") declaration at
the start of the file. This provides a static variable
of the virLogSource type.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

Consistently use "is" or "is not" to compare variables to None,
because doing so is preferrable, as per PEP 8
(http://www.python.org/dev/peps/pep-0008/#programming-recommendations):

> Comparisons to singletons like None should always be done with is or
> is not, never the equality operators.

Signed-off-by: NEric Blake <eblake@redhat.com>

This patch implements extensible variants of all internal migration APIs
used for v3 migration.

All APIs that take typed parameters are only using params address in
their entry point debug messages. With the new VIR_TYPED_PARAMS_DEBUG
macro, all functions can easily log all individual typed parameters
passed to them.

This API is useful for checking whether only a specific subset of
supported typed parameters were passed.

Ensure that the driver struct field names match the public
API names. For an API virXXXX we must have a driver struct
field xXXXX. ie strip the leading 'vir' and lowercase any
leading uppercase letters.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

Commit 6094ad7b (0.9.3 release) promoted several functions from
internal to public, but forgot to fix the documentation generator
to provide details about those functions.

For an example of what this fixes, look at:
file:///path/to/libvirt/docs/html/libvirt-libvirt.html#virEventAddHandle
before and after the patch.

* docs/apibuild.py (ignored_functions): Don't ignore functions
that were turned into official API.
* src/util/virevent.c: Fix comments to pass through parser.

When a function has no associated information to one of its
arguments or its return type we report it and stop with an error.