X-Git-Url: http://git.imager.perl.org/imager.git/blobdiff_plain/92bda6321b472bb18726d950da8833b950abf4ee..e17b7029eb8e9c20f30e5208de1f49d243fa514c:/apidocs.perl

diff --git a/apidocs.perl b/apidocs.perl
index 366c425a..87c79b3c 100644
--- a/apidocs.perl
+++ b/apidocs.perl
@@ -1,15 +1,16 @@
 #!perl -w
 use strict;
+use ExtUtils::Manifest 'maniread';
 
 my $outname = shift || '-';
 
-
 my @funcs = make_func_list();
 my %funcs = map { $_ => 1 } @funcs;
 
 # look for files to parse
 
-my @files = grep $_ ne 'Imager.xs', glob '*.c';
+my $mani = maniread;
+my @files = grep /\.(c|im|h)$/, keys %$mani;
 
 # scan each file for =item <func>\b
 my $func;
@@ -22,6 +23,8 @@ my %funccats;
 my %cats;
 my $synopsis = '';
 my %funcsyns;
+my $order;
+my %order;
 for my $file (@files) {
   open SRC, "< $file"
     or die "Cannot open $file for documentation: $!\n";
@@ -34,7 +37,7 @@ for my $file (@files) {
     elsif ($func && /^=(cut|head)/) {
       if ($funcs{$func}) { # only save the API functions
         $alldocs{$func} = [ @funcdocs ];
-        $from{$func} = "Line $start in $file";
+        $from{$func} = "File $file";
         if ($category) {
           $funccats{$func} = $category;
           push @{$cats{$category}}, $func;
@@ -42,9 +45,12 @@ for my $file (@files) {
         if ($synopsis) {
           $funcsyns{$func} = $synopsis;
         }
+	defined $order or $order = 50;
+	$order{$func} = $order;
       }
       undef $func;
       undef $category;
+      undef $order;
       $synopsis = '';
     }
     elsif ($func) {
@@ -54,6 +60,11 @@ for my $file (@files) {
       elsif (/^=synopsis (.*)/) {
         $synopsis .= "$1\n";
       }
+      elsif (/^=order (.*)$/) {
+	$order = $1;
+	$order =~ /^\d+$/
+	  or die "=order must specify a number for $func in $file\n";
+      }
       else {
         push @funcdocs, $_;
       }
@@ -72,24 +83,23 @@ print OUT <<'EOS';
 Do not edit this file, it is generated automatically by apidocs.perl
 from Imager's source files.
 
-Each function description has a comment listing the source file and
-line number where you can find the documentation.
+Each function description has a comment listing the source file where
+you can find the documentation.
 
 =head1 NAME
 
-Imager::APIRef - Imager's C API.
+Imager::APIRef - Imager's C API - reference.
 
 =head1 SYNOPSIS
 
   i_color color;
-  color.rgba.red = 255; color.rgba.green = 0; color.rgba.blue = 255;
-  i_fill_t *fill = i_new_fill_...(...);
+  color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
 
 EOS
 
 for my $cat (sort { lc $a cmp lc $b } keys %cats) {
   print OUT "\n  # $cat\n";
-  for my $func (grep $funcsyns{$_}, sort @{$cats{$cat}}) {
+  for my $func (grep $funcsyns{$_}, sort { $order{$a} <=> $order{$b} } @{$cats{$cat}}) {
     my $syn = $funcsyns{$func};
     $syn =~ s/^/  /gm;
     print OUT $syn;
@@ -98,8 +108,6 @@ for my $cat (sort { lc $a cmp lc $b } keys %cats) {
 
 print OUT <<'EOS';
 
-   i_fill_destroy(fill);
-
 =head1 DESCRIPTION
 
 EOS
@@ -108,7 +116,11 @@ my %undoc = %funcs;
 
 for my $cat (sort { lc $a cmp lc $b } keys %cats) {
   print OUT "=head2 $cat\n\n=over\n\n";
-  for my $func (sort @{$cats{$cat}}) {
+  my @ordered_funcs = sort {
+    $order{$a} <=> $order{$b}
+      || lc $a cmp lc $b
+    } @{$cats{$cat}};
+  for my $func (@ordered_funcs) {
     print OUT @{$alldocs{$func}}, "\n";
     print OUT "=for comment\nFrom: $from{$func}\n\n";
     delete $undoc{$func};
@@ -119,12 +131,12 @@ for my $cat (sort { lc $a cmp lc $b } keys %cats) {
 # see if we have an uncategorized section
 if (grep $alldocs{$_}, keys %undoc) {
   print OUT "=head2 Uncategorized functions\n\n=over\n\n";
-  for my $func (sort @funcs) {
-    if ($undoc{$func} && $alldocs{$func}) {
-      print OUT @{$alldocs{$func}}, "\n";
-      print OUT "=for comment\nFrom: $from{$func}\n\n";
-      delete $undoc{$func};
-    }
+  #print join(",", grep !exists $order{$_}, @funcs), "\n";
+  for my $func (sort { $order{$a} <=> $order{$b} || $a cmp $b }
+		grep $undoc{$_} && $alldocs{$_}, @funcs) {
+    print OUT @{$alldocs{$func}}, "\n";
+    print OUT "=for comment\nFrom: $from{$func}\n\n";
+    delete $undoc{$func};
   }
   print OUT "\n\n=back\n\n";
 }
@@ -163,7 +175,7 @@ close OUT;
 
 
 sub make_func_list {
-  my $funcs;
+  my @funcs = qw(i_img i_color i_fcolor i_fill_t mm_log i_img_color_channels i_img_has_alpha i_img_dim);
   open FUNCS, "< imexttypes.h"
     or die "Cannot open imexttypes.h: $!\n";
   my $in_struct;
@@ -187,3 +199,45 @@ sub make_func_list {
     die "Found neither the start nor end of the functions structure\n";
   }
 }
+
+=head1 NAME
+
+apidocs.perl - parse Imager's source for POD documenting the C API
+
+=head1 SYNOPSIS
+
+  perl apidocs.perl lib/Imager/APIRef.pod
+
+=head1 DESCRIPTION
+
+Parses Imager's C sources, including .c, .h and .im files searching
+for function documentation.
+
+Besides the normal POD markup, the following can be included:
+
+=over
+
+=item =category I<category-name>
+
+The category the function should be in.
+
+=item =synopsis I<sample-code>
+
+Sample code using the function to include in the Imager::APIRef SYNOPSIS
+
+=item =order I<integer>
+
+Allows a function to be listed out of order.  If this isn't specified
+it defaults to 50, so a value of 10 will cause the function to be
+listed at the beginning of its category, or 90 to list at the end.
+
+Functions with equal order are otherwise ordered by name.
+
+=back
+
+=head1 AUTHOR
+
+Tony Cook <tonyc@cpan.org>
+
+=cut
+