Bug 869130 - [Doc] Perl-Sys-Virt doc has some format problem
Summary: [Doc] Perl-Sys-Virt doc has some format problem
Keywords:
Status: CLOSED ERRATA
Alias: None
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: perl-Sys-Virt
Version: 6.4
Hardware: x86_64
OS: Linux
low
low
Target Milestone: rc
: ---
Assignee: Daniel Berrangé
QA Contact: Virtualization Bugs
URL:
Whiteboard:
Depends On:
Blocks: 881827
TreeView+ depends on / blocked
 
Reported: 2012-10-23 06:27 UTC by weizhang
Modified: 2013-02-21 09:52 UTC (History)
3 users (show)

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.
Clone Of:
Environment:
Last Closed: 2013-02-21 09:52:29 UTC
Target Upstream Version:


Attachments (Terms of Use)


Links
System ID Private Priority Status Summary Last Updated
Red Hat Product Errata RHBA-2013:0377 0 normal SHIPPED_LIVE perl-Sys-Virt bug fix and enhancement update 2013-02-20 20:52:18 UTC

Description weizhang 2012-10-23 06:27:37 UTC
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 08:01:41 UTC
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 08:47:46 UTC
(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 Berrangé 2012-11-16 14:38:28 UTC
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-20 03:27:13 UTC
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 09:52:29 UTC
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.