Mercurial > hg > octave-terminal
changeset 11153:3ddf14b8196f
New verification script, mk_undocumented_list, produces a list of undocumented functions.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Sun, 24 Oct 2010 08:33:10 -0700 |
parents | 39ae406df598 |
children | 92a7c136ab35 |
files | doc/ChangeLog doc/interpreter/doccheck/README doc/interpreter/doccheck/mk_undocumented_list |
diffstat | 3 files changed, 150 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -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
--- a/doc/interpreter/doccheck/README +++ b/doc/interpreter/doccheck/README @@ -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. +
new file mode 100755 --- /dev/null +++ b/doc/interpreter/doccheck/mk_undocumented_list @@ -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