[libvirt] [PATCH 0/3] Fix for generated api docs
The Makefile.am adjustment works for me - although it's not my preferred area of the environment to touch, so if there's a "better" way - let me know. The GetAllDomainStats current output is just an unreadable mass. This cleans it up a bit creating text/code boxes for the various stats. The InterfaceAddresses current output was about 1/2 right - this just makes all the code examples inside a text/code box. John Ferlan (3): docs: Rebuild apihtml docs when source changes docs: Adjust formatting for virConnectGetAllDomainStats output docs: Fix code example formatting for virDomainInterfaceAddresses docs/Makefile.am | 14 ++- src/libvirt-domain.c | 273 +++++++++++++++++++++++++++------------------------ 2 files changed, 157 insertions(+), 130 deletions(-) -- 2.7.4
When changing one of the src/libvirt-*.c files to alter the docs, the adjusted files weren't being built. Added them into APIBUILD_STAMP and then added that to the html/index.html rule which is used for the $(apihtml_generated) generated rule. Also, for clean we can remove the html/*.html files Signed-off-by: John Ferlan <jferlan@redhat.com> --- docs/Makefile.am | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index dbc6c0d..790c0a2 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -246,7 +246,7 @@ $(srcdir)/hvsupport.html.in: $(srcdir)/hvsupport.pl $(api_DATA) \ $(apihtml_generated): html/index.html -html/index.html: libvirt-api.xml newapi.xsl page.xsl +html/index.html: libvirt-api.xml newapi.xsl page.xsl $(APIBUILD_STAMP) $(AM_V_GEN)if [ -x $(XSLTPROC) ] ; then \ $(XSLTPROC) --nonet -o $(srcdir)/ \ --stringparam builddir '$(abs_top_builddir)' \ @@ -304,6 +304,16 @@ $(APIBUILD_STAMP): $(srcdir)/apibuild.py \ $(top_srcdir)/include/libvirt/libvirt-admin.h \ $(top_srcdir)/include/libvirt/virterror.h \ $(top_srcdir)/src/libvirt.c \ + $(top_srcdir)/src/libvirt-domain-snapshot.c \ + $(top_srcdir)/src/libvirt-domain.c \ + $(top_srcdir)/src/libvirt-host.c \ + $(top_srcdir)/src/libvirt-interface.c \ + $(top_srcdir)/src/libvirt-network.c \ + $(top_srcdir)/src/libvirt-nodedev.c \ + $(top_srcdir)/src/libvirt-nwfilter.c \ + $(top_srcdir)/src/libvirt-secret.c \ + $(top_srcdir)/src/libvirt-storage.c \ + $(top_srcdir)/src/libvirt-stream.c \ $(top_srcdir)/src/libvirt-lxc.c \ $(top_srcdir)/src/libvirt-qemu.c \ $(top_srcdir)/src/libvirt-admin.c \ @@ -318,7 +328,7 @@ check-local: all dist-local: all clean-local: - rm -f *~ *.bak *.hierarchy *.signals *-unused.txt *.html + rm -f *~ *.bak *.hierarchy *.signals *-unused.txt *.html html/*.html maintainer-clean-local: clean-local rm -rf $(srcdir)/libvirt-api.xml $(srcdir)/libvirt-refs.xml -- 2.7.4
Adjust the spacing a bit in order to generate 'cleaner' looking output. This matches what virDomainMemoryStats does and it creates text/code boxes in order to list each of the stats for each category. Signed-off-by: John Ferlan <jferlan@redhat.com> --- src/libvirt-domain.c | 222 +++++++++++++++++++++++++++------------------------ 1 file changed, 119 insertions(+), 103 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index ce199f0..9cd99bb 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -11108,111 +11108,127 @@ virConnectGetDomainCapabilities(virConnectPtr conn, * binary-OR of enum virDomainStatsTypes. The following groups are available * (although not necessarily implemented for each hypervisor): * - * VIR_DOMAIN_STATS_STATE: Return domain state and reason for entering that - * state. The typed parameter keys are in this format: - * "state.state" - state of the VM, returned as int from virDomainState enum - * "state.reason" - reason for entering given state, returned as int from - * virDomain*Reason enum corresponding to given state. - * - * VIR_DOMAIN_STATS_CPU_TOTAL: Return CPU statistics and usage information. - * The typed parameter keys are in this format: - * "cpu.time" - total cpu time spent for this domain in nanoseconds - * as unsigned long long. - * "cpu.user" - user cpu time spent in nanoseconds as unsigned long long. - * "cpu.system" - system cpu time spent in nanoseconds as unsigned long long. - * - * VIR_DOMAIN_STATS_BALLOON: Return memory balloon device information. - * The typed parameter keys are in this format: - * "balloon.current" - the memory in kiB currently used - * as unsigned long long. - * "balloon.maximum" - the maximum memory in kiB allowed - * as unsigned long long. - * - * VIR_DOMAIN_STATS_VCPU: Return virtual CPU statistics. - * Due to VCPU hotplug, the vcpu.<num>.* array could be sparse. - * The actual size of the array corresponds to "vcpu.current". - * The array size will never exceed "vcpu.maximum". - * The typed parameter keys are in this format: - * "vcpu.current" - current number of online virtual CPUs as unsigned int. - * "vcpu.maximum" - maximum number of online virtual CPUs as unsigned int. - * "vcpu.<num>.state" - state of the virtual CPU <num>, as int - * from virVcpuState enum. - * "vcpu.<num>.time" - virtual cpu time spent by virtual CPU <num> - * as unsigned long long. - * - * VIR_DOMAIN_STATS_INTERFACE: Return network interface statistics. - * The typed parameter keys are in this format: - * "net.count" - number of network interfaces on this domain - * as unsigned int. - * "net.<num>.name" - name of the interface <num> as string. - * "net.<num>.rx.bytes" - bytes received as unsigned long long. - * "net.<num>.rx.pkts" - packets received as unsigned long long. - * "net.<num>.rx.errs" - receive errors as unsigned long long. - * "net.<num>.rx.drop" - receive packets dropped as unsigned long long. - * "net.<num>.tx.bytes" - bytes transmitted as unsigned long long. - * "net.<num>.tx.pkts" - packets transmitted as unsigned long long. - * "net.<num>.tx.errs" - transmission errors as unsigned long long. - * "net.<num>.tx.drop" - transmit packets dropped as unsigned long long. - * - * VIR_DOMAIN_STATS_BLOCK: Return block devices statistics. By default, - * this information is limited to the active layer of each <disk> of the - * domain (where block.count is equal to the number of disks), but adding - * VIR_CONNECT_GET_ALL_DOMAINS_STATS_BACKING to @flags will expand the - * array to cover backing chains (block.count corresponds to the number - * of host resources used together to provide the guest disks). - * The typed parameter keys are in this format: - * "block.count" - number of block devices in the subsequent list, - * as unsigned int. - * "block.<num>.name" - name of the block device <num> as string. - * matches the target name (vda/sda/hda) of the - * block device. If the backing chain is listed, - * this name is the same for all host resources tied - * to the same guest device. - * "block.<num>.backingIndex" - unsigned int giving the <backingStore> index, - * only used when backing images are listed. - * "block.<num>.path" - string describing the source of block device <num>, - * if it is a file or block device (omitted for network - * sources and drives with no media inserted). - * "block.<num>.rd.reqs" - number of read requests as unsigned long long. - * "block.<num>.rd.bytes" - number of read bytes as unsigned long long. - * "block.<num>.rd.times" - total time (ns) spent on reads as - * unsigned long long. - * "block.<num>.wr.reqs" - number of write requests as unsigned long long. - * "block.<num>.wr.bytes" - number of written bytes as unsigned long long. - * "block.<num>.wr.times" - total time (ns) spent on writes as - * unsigned long long. - * "block.<num>.fl.reqs" - total flush requests as unsigned long long. - * "block.<num>.fl.times" - total time (ns) spent on cache flushing as - * unsigned long long. - * "block.<num>.errors" - Xen only: the 'oo_req' value as - * unsigned long long. - * "block.<num>.allocation" - offset of the highest written sector - * as unsigned long long. - * "block.<num>.capacity" - logical size in bytes of the block device backing - * image as unsigned long long. - * "block.<num>.physical" - physical size in bytes of the container of the - * backing image as unsigned long long. - * - * VIR_DOMAIN_STATS_PERF: Return perf event statistics. - * The typed parameter keys are in this format: - * "perf.cmt" - the usage of l3 cache (bytes) by applications running on the - * platform as unsigned long long. It is produced by cmt perf - * event. - * "perf.mbmt" - the total system bandwidth (bytes/s) from one level of cache - * to another as unsigned long long. It is produced by mbmt perf - * event. - * "perf.mbml" - the amount of data (bytes/s) sent through the memory controller - * on the socket as unsigned long long. It is produced by mbml - * perf event. - * "perf.cache_misses" - the count of cache misses as unsigned long long. + * VIR_DOMAIN_STATS_STATE: + * Return domain state and reason for entering that state. The typed + * parameter keys are in this format: + * + * "state.state" - state of the VM, returned as int from virDomainState enum + * "state.reason" - reason for entering given state, returned as int from + * virDomain*Reason enum corresponding to given state. + * + * VIR_DOMAIN_STATS_CPU_TOTAL: + * Return CPU statistics and usage information. The typed parameter keys + * are in this format: + * + * "cpu.time" - total cpu time spent for this domain in nanoseconds + * as unsigned long long. + * "cpu.user" - user cpu time spent in nanoseconds as unsigned long long. + * "cpu.system" - system cpu time spent in nanoseconds as unsigned long + * long. + * + * VIR_DOMAIN_STATS_BALLOON: + * Return memory balloon device information. + * The typed parameter keys are in this format: + * + * "balloon.current" - the memory in kiB currently used + * as unsigned long long. + * "balloon.maximum" - the maximum memory in kiB allowed + * as unsigned long long. + * + * VIR_DOMAIN_STATS_VCPU: + * Return virtual CPU statistics. + * Due to VCPU hotplug, the vcpu.<num>.* array could be sparse. + * The actual size of the array corresponds to "vcpu.current". + * The array size will never exceed "vcpu.maximum". + * The typed parameter keys are in this format: + * + * "vcpu.current" - current number of online virtual CPUs as unsigned int. + * "vcpu.maximum" - maximum number of online virtual CPUs as unsigned int. + * "vcpu.<num>.state" - state of the virtual CPU <num>, as int + * from virVcpuState enum. + * "vcpu.<num>.time" - virtual cpu time spent by virtual CPU <num> + * as unsigned long long. + * + * VIR_DOMAIN_STATS_INTERFACE: + * Return network interface statistics. + * The typed parameter keys are in this format: + * + * "net.count" - number of network interfaces on this domain + * as unsigned int. + * "net.<num>.name" - name of the interface <num> as string. + * "net.<num>.rx.bytes" - bytes received as unsigned long long. + * "net.<num>.rx.pkts" - packets received as unsigned long long. + * "net.<num>.rx.errs" - receive errors as unsigned long long. + * "net.<num>.rx.drop" - receive packets dropped as unsigned long long. + * "net.<num>.tx.bytes" - bytes transmitted as unsigned long long. + * "net.<num>.tx.pkts" - packets transmitted as unsigned long long. + * "net.<num>.tx.errs" - transmission errors as unsigned long long. + * "net.<num>.tx.drop" - transmit packets dropped as unsigned long long. + * + * VIR_DOMAIN_STATS_BLOCK: + * Return block devices statistics. By default, + * this information is limited to the active layer of each <disk> of the + * domain (where block.count is equal to the number of disks), but adding + * VIR_CONNECT_GET_ALL_DOMAINS_STATS_BACKING to @flags will expand the + * array to cover backing chains (block.count corresponds to the number + * of host resources used together to provide the guest disks). + * The typed parameter keys are in this format: + * + * "block.count" - number of block devices in the subsequent list, + * as unsigned int. + * "block.<num>.name" - name of the block device <num> as string. + * matches the target name (vda/sda/hda) of the + * block device. If the backing chain is listed, + * this name is the same for all host resources tied + * to the same guest device. + * "block.<num>.backingIndex" - unsigned int giving the <backingStore> + * index, only used when backing images + * are listed. + * "block.<num>.path" - string describing the source of block device <num>, + * if it is a file or block device (omitted for network + * sources and drives with no media inserted). + * "block.<num>.rd.reqs" - number of read requests as unsigned long long. + * "block.<num>.rd.bytes" - number of read bytes as unsigned long long. + * "block.<num>.rd.times" - total time (ns) spent on reads as + * unsigned long long. + * "block.<num>.wr.reqs" - number of write requests as unsigned long long. + * "block.<num>.wr.bytes" - number of written bytes as unsigned long long. + * "block.<num>.wr.times" - total time (ns) spent on writes as + * unsigned long long. + * "block.<num>.fl.reqs" - total flush requests as unsigned long long. + * "block.<num>.fl.times" - total time (ns) spent on cache flushing as + * unsigned long long. + * "block.<num>.errors" - Xen only: the 'oo_req' value as + * unsigned long long. + * "block.<num>.allocation" - offset of the highest written sector + * as unsigned long long. + * "block.<num>.capacity" - logical size in bytes of the block device + * backing image as unsigned long long. + * "block.<num>.physical" - physical size in bytes of the container of the + * backing image as unsigned long long. + * + * VIR_DOMAIN_STATS_PERF: + * Return perf event statistics. + * The typed parameter keys are in this format: + * + * "perf.cmt" - the usage of l3 cache (bytes) by applications running on + * the platform as unsigned long long. It is produced by cmt + * perf event. + * "perf.mbmt" - the total system bandwidth (bytes/s) from one level of + * cache to another as unsigned long long. It is produced + * by mbmt perf event. + * "perf.mbml" - the amount of data (bytes/s) sent through the memory + * controller on the socket as unsigned long long. It is + * produced by mbml perf event. + * "perf.cache_misses" - the count of cache misses as unsigned long long. * It is produced by cache_misses perf event. - * "perf.cache_references" - the count of cache hits as unsigned long long. - * It is produced by cache_references perf event. - * "perf.instructions" - The count of instructions as unsigned long long. + * "perf.cache_references" - the count of cache hits as unsigned long long. + * It is produced by cache_references perf event. + * "perf.instructions" - The count of instructions as unsigned long long. * It is produced by instructions perf event. - * "perf.cpu_cycles" - The count of cpu cycles (total/elapsed) as an - * unsigned long long. It is produced by cpu_cycles - * perf event. + * "perf.cpu_cycles" - The count of cpu cycles (total/elapsed) as an + * unsigned long long. It is produced by cpu_cycles + * perf event. * * Note that entire stats groups or individual stat fields may be missing from * the output in case they are not supported by the given hypervisor, are not -- 2.7.4
Adjust the spacing so that the code examples are display in the code/text box rather than just as paragraph text. Signed-off-by: John Ferlan <jferlan@redhat.com> --- src/libvirt-domain.c | 51 ++++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 9cd99bb..e0f4a51 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -11523,34 +11523,35 @@ virDomainFSInfoFree(virDomainFSInfoPtr info) * The caller *must* free @ifaces when no longer needed. Usual use case * looks like this: * - * virDomainInterfacePtr *ifaces = NULL; - * int ifaces_count = 0; - * size_t i, j; - * virDomainPtr dom = ... obtain a domain here ...; + * virDomainInterfacePtr *ifaces = NULL; + * int ifaces_count = 0; + * size_t i, j; + * virDomainPtr dom = ... obtain a domain here ...; * - * if ((ifaces_count = virDomainInterfaceAddresses(dom, &ifaces, - * VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE)) < 0) - * goto cleanup; + * if ((ifaces_count = virDomainInterfaceAddresses(dom, &ifaces, + * VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE)) < 0) + * goto cleanup; * * ... do something with returned values, for example: - * for (i = 0; i < ifaces_count; i++) { - * printf("name: %s", ifaces[i]->name); - * if (ifaces[i]->hwaddr) - * printf(" hwaddr: %s", ifaces[i]->hwaddr); - * - * for (j = 0; j < ifaces[i]->naddrs; j++) { - * virDomainIPAddressPtr ip_addr = ifaces[i]->addrs + j; - * printf("[addr: %s prefix: %d type: %d]", - * ip_addr->addr, ip_addr->prefix, ip_addr->type); - * } - * printf("\n"); - * } - * - * cleanup: - * if (ifaces && ifaces_count > 0) - * for (i = 0; i < ifaces_count; i++) - * virDomainInterfaceFree(ifaces[i]); - * free(ifaces); + * + * for (i = 0; i < ifaces_count; i++) { + * printf("name: %s", ifaces[i]->name); + * if (ifaces[i]->hwaddr) + * printf(" hwaddr: %s", ifaces[i]->hwaddr); + * + * for (j = 0; j < ifaces[i]->naddrs; j++) { + * virDomainIPAddressPtr ip_addr = ifaces[i]->addrs + j; + * printf("[addr: %s prefix: %d type: %d]", + * ip_addr->addr, ip_addr->prefix, ip_addr->type); + * } + * printf("\n"); + * } + * + * cleanup: + * if (ifaces && ifaces_count > 0) + * for (i = 0; i < ifaces_count; i++) + * virDomainInterfaceFree(ifaces[i]); + * free(ifaces); * * Returns the number of interfaces on success, -1 in case of error. */ -- 2.7.4
On 06.12.2016 14:57, John Ferlan wrote:
The Makefile.am adjustment works for me - although it's not my preferred area of the environment to touch, so if there's a "better" way - let me know.
The GetAllDomainStats current output is just an unreadable mass. This cleans it up a bit creating text/code boxes for the various stats.
The InterfaceAddresses current output was about 1/2 right - this just makes all the code examples inside a text/code box.
John Ferlan (3): docs: Rebuild apihtml docs when source changes docs: Adjust formatting for virConnectGetAllDomainStats output docs: Fix code example formatting for virDomainInterfaceAddresses
docs/Makefile.am | 14 ++- src/libvirt-domain.c | 273 +++++++++++++++++++++++++++------------------------ 2 files changed, 157 insertions(+), 130 deletions(-)
ACK Michal
participants (2)
-
John Ferlan -
Michal Privoznik