[Pkg-ocaml-maint-commits] [SCM] dh-ocaml packaging branch, master, updated. debian/0.5.0-18-g425529d

[Mehdi Dogguy]

The following commit has been merged in the master branch:
commit 425529d25991f0e175b5838e4022e142dfb161c2
Author: Mehdi Dogguy <dogguy at pps.jussieu.fr>
Date:   Wed Jul 22 02:32:36 2009 +0200

    Add some comments in the source code of dh_ocamldoc

diff --git a/debhelper/dh_ocamldoc b/debhelper/dh_ocamldoc
index 462894b..8277df8 100755
--- a/debhelper/dh_ocamldoc
+++ b/debhelper/dh_ocamldoc
@@ -61,13 +61,22 @@ chomp $ocaml_lib_dir;
 error "$odoc does not exists or is not executable"
     unless -x $odoc;
 
+# Returns the destination directory where the documentation will be
+# @args: package   the current processed binary package name
+#        html_dir  the subdirectory where the documentation will end
+#
 sub ocamldoc_destdir_html($$) {
     my ($package, $html_dir) = @_;
     return "/usr/share/doc/$package/$html_dir/";
 }
 
-sub generate_docbase($$$$) {
-    my ($package, $tmp_dir, $html_dir, $document_name) = @_;
+# Generate the docbase file for a given package
+# @args: package         the current processed binary package name
+#        html_dir        the subdirectory where the documentation will end
+#        document_name   doc-base document id
+#
+sub generate_docbase($$$) {
+    my ($package, $html_dir, $document_name) = @_;
     my $dest_dir = ocamldoc_destdir_html($package, $html_dir);
     my $file = "debian/${package}.doc-base.apiref${document_name}";
     verbose_print("Generating doc-base file: $file");
@@ -84,6 +93,9 @@ sub generate_docbase($$$$) {
     close(DOC);
 }
 
+# Read ocamldoc file for a package
+# @args: file   file to read
+#
 sub read_ocamldoc_file($) {
     my ($file) = @_;
     open (OCAMLDOC, "< $file");
@@ -91,8 +103,11 @@ sub read_ocamldoc_file($) {
     my $html_dir = "html/api";
     my $content = "";
     while (<OCAMLDOC>) {
+        # Skip comments
         next if /^\#/;
+        # Activate ocamlfind when needed
         $use_ocamlfind = 1 if / -package | -predicates | -syntax | -ppopt /;
+        # Detect html_dir
         if (/-d[\s]+([^\s]+)/) {
             $html_dir = $1;
         }
@@ -104,10 +119,15 @@ sub read_ocamldoc_file($) {
     return ($content, $html_dir, $use_ocamlfind);
 }
 
+# Generate all documentations and doc-base files for a binary package
+# @args: package          the current processed binary package name
+#        ocamldoc_files   .ocamldoc files to process
+#
 sub do_doc_package($@) {
     my ($package, @ocamldoc_files) = @_;
     foreach my $fdoc (@ocamldoc_files) {
         my $ocamldoc = $odoc;
+        # Set doc-base document id
         my $document_name = $fdoc;
         $document_name =~ s/debian\/.*\.ocamldoc//g;
         my ($ocamldoc_flags, $html_dir, $use_ocamlfind) = read_ocamldoc_file($fdoc);
@@ -120,10 +140,11 @@ sub do_doc_package($@) {
         $ocamldoc = "ocamlfind ocamldoc" if $use_ocamlfind;
         complex_doit("mkdir -p $tmpdir$dest_dir");
         my $doc_files = `find ${search_dir} -type f -name '*.mli' -or -name '*.ml' | xargs echo || true`;
+        # Don't generate documentation when there is no source file nor included directories
         if (! ($doc_files =~ "" and $ocamldoc_flags =~ /-I .*/)) {
             $doc_files =~ s/\n//g;
             complex_doit("$ocamldoc $ocamldoc_flags -html -stars -m A -d $tmpdir$dest_dir $doc_files");
-            generate_docbase($package, $tmpdir, $html_dir, $document_name);
+            generate_docbase($package, $html_dir, $document_name);
         } else {
             warning("No doc files (*.mli or *.ml), nor included directories. Nothing to do...");
         }
@@ -132,9 +153,15 @@ sub do_doc_package($@) {
 
 foreach my $pkg (@{$dh{DOPACKAGES}}) {
     my $tmp_dir = tmpdir($pkg);
-    my @files = pkgfile($pkg, "ocamldoc");
     my @ocamldoc_files = split /\n/,
     `find debian/ -type f -name "$pkg.ocamldoc*"`;
+    if ($pkg =~ $dh{MAINPACKAGE}) {
+      my @list = split /\n/, `find debian -type f -name "ocamldoc*"`;
+      # Possible nameclash here but done on purpose since the packager
+      # can always have several ocamldoc files but should choose a coherent
+      # name convetion.
+      @ocamldoc_file = merge(@ocamldoc_files, @list);
+    }
     if (@ocamldoc_files) {
         verbose_print("Generating documentation for $pkg");
         do_doc_package($pkg, @ocamldoc_files);

-- 
dh-ocaml packaging