Bug 869130 - [Doc] Perl-Sys-Virt doc has some format problem
[Doc] Perl-Sys-Virt doc has some format problem
Status: CLOSED ERRATA
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: perl-Sys-Virt (Show other bugs)
6.4
x86_64 Linux
low Severity low
: rc
: ---
Assigned To: Daniel Berrange
Virtualization Bugs
:
Depends On:
Blocks: 881827
  Show dependency treegraph
 
Reported: 2012-10-23 02:27 EDT by weizhang
Modified: 2013-02-21 04:52 EST (History)
3 users (show)

See Also:
Fixed In Version: perl-Sys-Virt-0.10.2-4.el6
Doc Type: Bug Fix
Doc Text:
Cause: A number of mistakes were made in the API documentation Consequence: The API documentation containing formatting errors Fix: The API docs were corrected. Result: The API documentation formats correctly.
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-02-21 04:52:29 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description weizhang 2012-10-23 02:27:37 EDT
Description of problem:
In doc /usr/share/man/man3/Sys::Virt::Domain.3pm.gz, after item
my $info = $dom->get_job_info()
    Returns a hash reference summarising the execution state of the background job. The elements of the hash are as follows:

the elements are listed after
$snapshot = $dom->create_snapshot($xml[, $flags])
           Create a new snapshot from the $xml. 

Also for create_snapshot there is no "flag" interpretation and the flags elements are not listed in Sys::Virt::Domain.3pm.gz but in Sys::Virt::DomainSnapshot.3pm.gz, they are should in the same doc for easy understanding, or some interpretation to tell the doc position of the creation flags in Sys::Virt::Domain.3pm.gz.

And in Sys::Virt::DomainSnapshot.3pm.gz, for
my @snapshots = $dom->list_all_children($flags)
the object should be $domss but not $dom

Version-Release number of selected component (if applicable):
perl-Sys-Virt-0.10.2-3.el6.x86_64

How reproducible:
100%

Steps to Reproduce:
1.#man /usr/share/man/man3/Sys::Virt::Domain.3pm.gz
2.#man /usr/share/man/man3/Sys::Virt::DomainSnapshot.3pm.gz
3.
  
Actual results:


Expected results:


Additional info:
Comment 1 weizhang 2012-10-23 04:01:41 EDT
Another problem is 
 @snapshots = $dom->list_all_snapshots($flags)
Can this flag be Sys::Virt::DomainSnapshot::LIST_DESCENDANTS? The current test result is the same as Sys::Virt::DomainSnapshot::LIST_ROOTS. If it can not be set, please report error, and add doc for it.
Comment 2 weizhang 2012-11-05 03:47:46 EST
(In reply to comment #1)
> Another problem is 
>  @snapshots = $dom->list_all_snapshots($flags)
> Can this flag be Sys::Virt::DomainSnapshot::LIST_DESCENDANTS? The current
> test result is the same as Sys::Virt::DomainSnapshot::LIST_ROOTS. If it can
> not be set, please report error, and add doc for it.

https://bugzilla.redhat.com/show_bug.cgi?id=869100#c3 here already explained detailed. Thanks
Comment 3 Daniel Berrange 2012-11-16 09:38:28 EST
Fixed in 2 commits

commit e2e9339a81fcb30578da52bf4ba07d72f183b9a7
Author: Daniel P. Berrange <berrange@redhat.com>
Date:   Fri Nov 16 13:25:41 2012 +0000

    Fix more POD mistakes related to snapshots
    

commit 8d246a8878116cfbcaea8c521810ef35e9bb8b09
Author: Daniel P. Berrange <berrange@redhat.com>
Date:   Fri Nov 16 13:22:05 2012 +0000

    Fix malformed POD docs for block job info hash fields
Comment 6 weizhang 2012-11-19 22:27:13 EST
Verify pass on
perl-Sys-Virt-0.10.2-4.el6.x86_64

1.
in /usr/share/man/man3/Sys::Virt::DomainSnapshot.3pm.gz, object changed from dom to domss
my @snapshots = $domss->list_all_children($flags)


2.
in /usr/share/man/man3/Sys::Virt::Domain.3pm.gz, the elements are followed after get_job_info
my $info = $dom->get_job_info()
  Returns a hash reference summarising the execution state of the background job. The elements of the hash are as follows:

  type
      The type of job, one of the JOB TYPE constants listed later in this document.

...


3. in /usr/share/man/man3/Sys::Virt::Domain.3pm.gz, there is flags parameter interpretation
$snapshot = $dom->create_snapshot($xml[, $flags])
  Create a new snapshot from the $xml. The $flags parameter accepts the SNAPSHOT CREATION constants listed in "Sys::Virt::DomainSnapshots".

So verify pass
Comment 8 errata-xmlrpc 2013-02-21 04:52:29 EST
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHBA-2013-0377.html

Note You need to log in before you can comment on or make changes to this bug.