GNOME.org
 

API Documentation Coverage, Take 2

Hello,

I have taken on board the suggestions made by Malcolm, regarding what
constitutes "completeness" for API documentation, and I have produced
some new data:

	http://www.employees.org/~kmsharp/apidoc.html

I've attached the two scripts I used to generate this HTML.  One is a
shell script which invokes a PERL script for each project/component in a
build tree.  To use these in your own environment you need to edit the
two variables at the top of the script apidoc.sh.  The result of running
the script is an HTML report sent to STDOUT.

Keith.

PS. You will notice that the numbers are the same as in my previous
email - jhbuild has stopped working, damn that libIDL :-)

#!/bin/bash
                                                                                
# Shell script to analyse undocumented APIs

# XXX - Change these two so they match your environment - XXX
BUILD="/misc/gnome/build"
APIPL="${HOME}/share/perl/apidoc.pl"

DATE=`date +%d-%b-%Y`

echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
echo "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\";>"
echo "<html xmlns=\"http://www.w3.org/1999/xhtml\"; xml:lang=\"en\" lang=\"en\">"
echo "<head><title>GNOME API Documentation Coverage</title></head>"
echo "<body><h1>GNOME API Documentation Coverage</h1>"
echo "<table>"
echo "<caption>Report from ${DATE}</caption>"
echo "<tr><th>Project</th><th>Coverage</th><th>Unused</th><th>Short</th><th>Long</th><th>Total</th></tr>"

for FILE in `find ${BUILD} -name "*-undocumented.txt" -print`; do
	PROJECT=`basename ${FILE} | awk -F"-un" '{print $1}'`
	DIR=`echo ${FILE} | awk -F"/${PROJECT}-undo" '{print $1}'`
	${APIPL} ${DIR} ${PROJECT}
done

echo "</table>"

echo "<ul>"
echo "<li>"
echo "<p><strong>Project</strong>: "
echo "The name of the component</p>"
echo "</li>"

echo "<li>"
echo "<p><strong>Coverage</strong>: "
echo "Percentage coverage of API documentation</p>"
echo "</li>"

echo "<li>"
echo "<p><strong>Unused</strong>: "
echo "Number of items in the <tt>*-unused.txt</tt> file</p>"
echo "</li>"

echo "<li>"
echo "<p><strong>Short</strong>: "
echo "The number of <tt>tmpl/*.sgml</tt> files with a short description</p>"
echo "</li>"

echo "<li>"
echo "<p><strong>Long</strong>: "
echo "The number of <tt>tmpl/*.sgml</tt> files with a long description</p>"
echo "</li>"

echo "<li>"
echo "<p><strong>Total</strong>: "
echo "The total number of <tt>tmpl/*.sgml</tt></p>"
echo "</li>"
echo "</ul>"

echo "</body></html>"

#!/usr/bin/perl

# Perl script to analyse the API docs in a GNOME project and produce 
# some nice statistics.

sub parse_undocumented {
	my $undoc_file = shift;
	
	if (! -e $undoc_file) {
		return "N/A ";
	}

	open (UNDOC, "$undoc_file") || die "Could not open file: $undoc_file";

	my @percent = split (/%/, <UNDOC>);

	close (UNDOC);
	return $percent[0];
}

sub parse_unused {
	my $number = 0;
	my $unused_file = shift;

	if (! -e $unused_file) {
		return $number;
	}

	open (UNUSED, "$unused_file") || die "Could not open file: $unused_file";

	while (<UNUSED>) {
		$number++;
	}

	close (UNUSED);
	return $number
}

sub find_short_desc {
	my $file = shift;
	my $short = 0;
	open (FILE, $file) || die "Could not open file: $file";

	while (<FILE>) {
		if ($_ =~ /Short_Description/) {
			while (<FILE>) {
				if ($_ =~ /Long_Description/) {
					$short = 0;
					last;
				} 
				if ($_ =~ /<para>/ || $_ =~ /<\/para>/) {
					$short = 0;
				} elsif ($_ =~ /\w/) {
					$short = 1;
					last;
				}
			}
		}
	}

	close FILE;
	return $short;
}

sub find_long_desc {
	my $file = shift;
	my $long = 0;
	open (FILE, $file) || die "Could not open file: $file";

	while (<FILE>) {
		if ($_ =~ /Long_Description/) {
			while (<FILE>) {
				if ($_ =~ /See_Also/) {
					$long = 0;
					last;
				} 
				if ($_ =~ /<para>/ || $_ =~ /<\/para>/) {
					$long = 0;
				} elsif ($_ =~ /\w/) {
					$long = 1;
					last;
				}
			}
		}
	}

	close FILE;
	return $long;
}

sub parse_tmpl {
	my $tmpl_dir = shift;
	my @result;
	$result[0] = 0;
	$result[1] = 0;
	$result[2] = 0;

	opendir(TMPLDIR, "$tmpl_dir") || die "Could not open directory: $tmpl_dir";
	@files = grep(/\.sgml$/, readdir(TMPLDIR));

	foreach $file (@files) {
		$result[0]++;

		if (find_short_desc ($tmpl_dir . "/" . $file)) {
			$result[1]++;
		}

		if (find_long_desc ($tmpl_dir . "/" . $file)) {
			$result[2]++;
		}
	}

	closedir(TMPLDIR);
	return @result;
}

my $dir = shift;
my $project = shift;

my $i = parse_undocumented ($dir . "/" . $project . "-undocumented.txt");
my $j = parse_unused ($dir . "/" . $project . "-unused.txt");
my @k = parse_tmpl ($dir . "/tmpl");

#              Name          Coverage    Unused       Short         Long          Total
print "<tr><td>$project</td><td>$i%</td><td>$j</td><td>$k[1]</td><td>$k[2]</td><td>$k[0]</td></tr>\n"
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]