[libconfig-model-dpkg-perl] 15/27: added doc

[dod at debian.org]

This is an automated email from the git hooks/post-receive script.

dod pushed a commit to branch master
in repository libconfig-model-dpkg-perl.

commit d4c57145fdf545e99a4d2789a8d9bbd6721dcd44
Author: Dominique Dumont <dod at debian.org>
Date:   Sat Dec 27 18:41:08 2014 +0100

    added doc
---
 lib/Dpkg/Copyright/Scanner.pm | 75 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 67 insertions(+), 8 deletions(-)

diff --git a/lib/Dpkg/Copyright/Scanner.pm b/lib/Dpkg/Copyright/Scanner.pm
index fd6f0bd..b52ae4c 100644
--- a/lib/Dpkg/Copyright/Scanner.pm
+++ b/lib/Dpkg/Copyright/Scanner.pm
@@ -233,20 +233,79 @@ __END__
 
 =head1 SYNOPSIS
 
- $ cme update dpkg-copyright
+ use Dpkg::Copyright::Scanner qw/print_copyright scan_files/;
+
+ # print copyright data on STDOUT
+ print_copyright;
+
+ # return a data structure containing copyright information
+ my @copyright_data = scan_files();
+
 
 =head1 DESCRIPTION
 
 This command scans current package directory to extract copyright and
-licensse information and store them in the Files sections of
-debian/copyright file.
+license information. Information are packed in a way to ease review and
+maintenance. Files informations are grouped with wildcards ('*') to reduce
+the list of files.
+
+=head1 METHODS
+
+=head2 print_copyright
+
+Print copyright information on STDOUT like L<scan_copyrights>.
+
+=head2 scan_files
+
+Return a data structure with copyright and license information.
 
-In debian package directory:
+The structure is a list of list:
 
-* run 'cme update dpkg-copyright' or 'cme update dpkg'  
-* check the result with your favorite VCS diff tool. (you do use 
-  a VCS for your package files, do you ?)
+ [
+   [
+     [ path1 ,path2, ...],
+     copyright,
+     license_short_name
+   ],
+   ...
+ ]
 
-Note: this command is experimental.
+Example:
+
+ [
+  [
+    [ '*' ],
+    '1994-2001, by Frank Pilhofer.',
+    'GPL-2+'
+  ],
+  [
+    [ 'pan/*' ],
+    '2002-2006, Charles Kerr <charles at rebelbase.com>',
+    'GPL-2'
+  ],
+  [
+    [
+      'pan/data/parts.cc',
+      'pan/data/parts.h'
+    ],
+    '2002-2007, Charles Kerr <charles at rebelbase.com>',
+    'GPL-2'
+  ],
+ ]
+
+=head1 BUGS
+
+Extracting license and copyright data from unstructured comments is not reliable.
+User must check manually the files when no copyright info is found or when the
+license is unknown.
+
+=head1 SEE ALSO
+
+L<license_check>, C<licensecheck2dep5> from C<cdbs> package
+
+=head1 AUTHOR
+
+Dominique Dumont <dod at debian.org>
 
 =cut
+

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libconfig-model-dpkg-perl.git