# HG changeset patch
# User Rik <octave@nomad.inbox5.com>
# Date 1287934390 25200
# Node ID 3ddf14b8196f0c4c58cd2c4bb549a401f993d0a7
# Parent  39ae406df5989689dfa447749ca7a4e154eb8a97
New verification script, mk_undocumented_list, produces a list of undocumented functions.

diff -r 39ae406df598 -r 3ddf14b8196f doc/ChangeLog
--- a/doc/ChangeLog	Sun Oct 24 07:33:34 2010 -0700
+++ b/doc/ChangeLog	Sun Oct 24 08:33:10 2010 -0700
@@ -1,3 +1,8 @@
+2010-10-24  Rik  <octave@nomad.inbox5.com>
+
+	* interpreter/doccheck/mk_undocumented_list: New verification
+	script produces a list of undocumented functions.
+
 2010-10-23  John W. Eaton  <jwe@octave.org>
 
 	* interpreter/io.txi (Simple File I/O): Document textscan and
diff -r 39ae406df598 -r 3ddf14b8196f doc/interpreter/doccheck/README
--- a/doc/interpreter/doccheck/README	Sun Oct 24 07:33:34 2010 -0700
+++ b/doc/interpreter/doccheck/README	Sun Oct 24 08:33:10 2010 -0700
@@ -6,15 +6,17 @@
 documentation.  These scripts are internal developer tools for ensuring 
 consistent documentation formats and avoiding misspellings.
 
-The scripts provide two services:
+The scripts provide 3 services:
 
 1) A spellchecker, built atop GNU Aspell with a private dictionary of keywords
    specific to Octave.
 
 2) A grammarchecker designed from scratch in Perl to ensure a common format
-   for Octave documentation and make use of as many features of Texinfo as 
+   for Octave documentation and to make use of as many features of Texinfo as 
    possible.
 
+3) A list of undocumented functions, i.e, those missing an @DOCSTRING reference
+   in the .txi files.
 
 ################################################################################
                                    FILES
@@ -27,6 +29,8 @@
 grammarcheck : Perl script to check Octave Texinfo documentation in a single
                m-file(.m), C++ file(.cc), or Texinfo file(.txi, .texi).
 
+mk_undocumented_list : Perl script to make undocumented function list
+
 ################################################################################
                                    USAGE
 ################################################################################
@@ -74,3 +78,12 @@
 GRAMMAR:
 
 To be added
+
+UNDOCUMENTED:
+
+From the doc/interpreter/ directory, type 'doccheck/mk_undocumented_list'.
+This will produce a list of undocumented functions on stdout.  
+
+Functions which don't require an @DOCSTRING reference can be added to the list
+of exceptions at the bottom of the mk_undocumented_list script.
+
diff -r 39ae406df598 -r 3ddf14b8196f doc/interpreter/doccheck/mk_undocumented_list
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/interpreter/doccheck/mk_undocumented_list	Sun Oct 24 08:33:10 2010 -0700
@@ -0,0 +1,130 @@
+#!/usr/bin/perl -w
+
+################################################################################
+# Get a list from Octave of all visible functions
+@octave_output = <<`_END_OCT_SCRIPT_`;
+../../run-octave --norc --silent --no-history --eval '\
+ funclist  = vertcat (__list_functions__ , __builtins__) \
+ disp("#!-separator-!#") \
+ where = cellfun (\@which, funclist, \"UniformOutput\", 0)' 
+_END_OCT_SCRIPT_
+
+die "Unable to invoke 'run-octave'.  Exiting\n" unless (@octave_output);
+
+################################################################################
+# Winnow list of functions that require a DOCSTRING
+
+$idx = 0;
+while (($_ = $octave_output[$idx++]) !~ /^#!-separator-!#$/)
+{
+   push(@all_functions, $1) if (/] = (\w+)$/);
+}
+while ($_ = $octave_output[$idx++])
+{
+   push(@where, $1) if (/] = (\S*)$/);
+}
+
+# Remove deprecated functions from the list of features requiring a DOCSTRING  
+FUNC: foreach $idx (0 .. $#where)
+{
+   next FUNC if ($where[$idx] =~ /deprecated/i);
+
+   push (@functions, $all_functions[$idx]); 
+}
+
+# Remove internal functions from the list of features requiring a DOCSTRING  
+@functions = grep (! /^__/, @functions);
+
+# Load list of function exceptions not requiring a DOCSTRING
+# Exception data is stored at the bottom of this script
+map { chomp, $exceptions{$_}=1; } <DATA>;
+
+# Remove exception data from the list of features requiring a DOCSTRING
+@functions = grep (! $exceptions{$_}, @functions);
+
+################################################################################
+# Get a list of all documented functions
+foreach $txi_file (glob("*.txi"))
+{
+   open(TXI_FILE, $txi_file) or die "Unable to open $txi_file for reading\n";
+   while (<TXI_FILE>)
+   {
+      $docstrings{$1} = 1 if (/\@DOCSTRING\((\w+)\)/) ;
+   }
+}
+
+################################################################################
+# Find features which have not been documented in the txi files
+@undocumented = grep (! $docstrings{$_}, @functions);
+
+# Exit successfully if no undocumented functions
+exit(0) if (! @undocumented);
+
+$, = "\n";  # Set output record separator
+print sort(@undocumented);
+exit(1);
+
+################################################################################
+# Exception list of functions not requiring a DOCSTRING
+################################################################################
+__DATA__
+angle
+bessel
+besselh
+besseli
+besselk
+bessely
+build_bc_overloads_expected
+chdir
+comma
+debug
+exit
+fntests
+gammaln
+geometryimages
+i
+inf
+interpimages
+inverse
+j
+J
+lower
+nan
+paren
+plotimages
+SEEK_CUR
+SEEK_END
+semicolon
+setenv
+sparseimages
+tbcover
+test_args
+test_bc_overloads
+test_classes
+test_contin
+test_diag_perm
+test_error
+test_for
+test_func
+test_global
+test_if
+test_io
+test_null_assign
+test_prefer
+test_range
+test_recursion
+test_return
+test_slice
+test_sparse
+test_string
+test_struct
+test_switch
+test_system
+test_transpose
+test_try
+test_unwind
+test_while
+toc
+triu
+unimplemented
+upper