view admin/check-doc-strings @ 105813:df4934f25eef

* textmodes/two-column.el (2C-split): * textmodes/texnfo-upd.el (texinfo-multi-file-included-list): * textmodes/tex-mode.el (tex-set-buffer-directory): * textmodes/spell.el (spell-region, spell-string): * textmodes/reftex.el (reftex-erase-buffer): (reftex-get-file-buffer-force, reftex-kill-temporary-buffers): * textmodes/reftex-toc.el (reftex-toc-promote-action): * textmodes/reftex-sel.el (reftex-get-offset, reftex-insert-docstruct) (reftex-select-item): * textmodes/reftex-ref.el (reftex-label-info-update) (reftex-offer-label-menu): * textmodes/reftex-index.el (reftex-index-change-entry) (reftex-index-phrases-info): * textmodes/reftex-global.el (reftex-create-tags-file) (reftex-save-all-document-buffers, reftex-ensure-write-access): * textmodes/reftex-dcr.el (reftex-echo-ref, reftex-echo-cite) (reftex-view-crossref-from-bibtex): * textmodes/reftex-cite.el (reftex-bibtex-selection-callback) (reftex-extract-bib-entries-from-thebibliography) (reftex-all-used-citation-keys, reftex-create-bibtex-file): * textmodes/refbib.el (r2b-capitalize-title): (r2b-convert-buffer, r2b-help): * textmodes/page-ext.el (pages-directory) (pages-directory-goto-with-mouse): * textmodes/bibtex.el (bibtex-validate-globally): * textmodes/bib-mode.el (bib-capitalize-title): * textmodes/artist.el (artist-clear-buffer, artist-system): * progmodes/xscheme.el (global-set-scheme-interaction-buffer): (local-set-scheme-interaction-buffer, xscheme-process-filter) (verify-xscheme-buffer, xscheme-enter-interaction-mode) (xscheme-enter-debugger-mode, xscheme-debugger-mode-p) (xscheme-send-control-g-interrupt, xscheme-start-process) (xscheme-process-sentinel, xscheme-cd): * progmodes/verilog-mode.el (verilog-read-always-signals) (verilog-set-define, verilog-getopt-file) (verilog-module-inside-filename-p): * progmodes/sh-script.el: * progmodes/python.el (python-pdbtrack-get-source-buffer) (python-pdbtrack-grub-for-buffer, python-execute-file): * progmodes/octave-inf.el (inferior-octave): * progmodes/idlwave.el (idlwave-scan-user-lib-files) (idlwave-shell-compile-helper-routines, idlwave-set-local) (idlwave-display-completion-list-xemacs, idlwave-list-abbrevs) (idlwave-display-completion-list-emacs, idlwave-list-load-path-shadows) (idlwave-completion-fontify-classes, idlwave-display-calling-sequence): * progmodes/idlw-shell.el (idlwave-shell-examine-display-clear) (idlwave-shell-filter, idlwave-shell-examine-highlight) (idlwave-shell-sentinel, idlwave-shell-filter-directory) (idlwave-shell-display-line, idlwave-shell-set-bp-in-module) (idlwave-shell-examine-display, idlwave-shell-run-region) (idlwave-shell-filter-bp, idlwave-shell-save-and-action) (idlwave-shell-sources-filter, idlwave-shell-goto-next-error): * progmodes/idlw-help.el (idlwave-help-get-special-help) (idlwave-help-get-help-buffer): * progmodes/gud.el (gud-basic-call, gud-find-class) (gud-tooltip-activate-mouse-motions-if-enabled): * progmodes/gdb-mi.el (gdb-mouse-toggle-breakpoint-fringe): * progmodes/ebrowse.el (ebrowse-member-table, ebrowse-save-tree-as) (ebrowse-view-exit-fn, ebrowse-tags-list-members-in-file) (ebrowse-tags-next-file): * progmodes/ebnf2ps.el (ebnf-generate-eps, ebnf-generate-eps) (ebnf-eps-production-list, ebnf-begin-file, ebnf-log) (ebnf-eps-finish-and-write): * progmodes/cpp.el (cpp-edit-save): * progmodes/cperl-mode.el (cperl-pod-to-manpage): * progmodes/cc-defs.el (c-emacs-features): * progmodes/antlr-mode.el (antlr-invalidate-context-cache) (antlr-directory-dependencies): * progmodes/ada-xref.el (ada-gnat-parse-gpr, ada-get-ali-file-name) (ada-run-application, ada-find-in-src-path, ada-goto-parent) (ada-find-any-references, ada-make-filename-from-adaname) (ada-make-body-gnatstub): * obsolete/rnews.el (news-list-news-groups): * obsolete/resume.el (resume-suspend-hook,resume-write-buffer-to-file): * obsolete/iso-acc.el (iso-acc-minibuf-setup): * net/rcirc.el (rcirc-debug): * net/newst-treeview.el (newsticker--treeview-list-add-item) (newsticker--treeview-list-clear, newsticker-treeview-browse-url) (newsticker--treeview-list-update-faces, newsticker-treeview-save) (newsticker--treeview-item-show-text, newsticker--treeview-item-show) (newsticker--treeview-tree-update-tag,newsticker--treeview-buffer-init) (newsticker-treeview-show-item, newsticker--treeview-unfold-node) (newsticker--treeview-list-clear-highlight) (newsticker--treeview-list-update-highlight) (newsticker--treeview-list-highlight-start) (newsticker--treeview-tree-update-highlight) (newsticker--treeview-get-selected-item) (newsticker-treeview-mark-list-items-old) (newsticker--treeview-set-current-node): * net/newst-plainview.el (newsticker--buffer-set-uptodate): * net/newst-backend.el (newsticker--get-news-by-funcall) (newsticker--get-news-by-wget, newsticker--image-get) (newsticker--image-sentinel): * net/mairix.el (mairix-rmail-fetch-field, mairix-gnus-fetch-field): * net/eudcb-ph.el (eudc-ph-do-request, eudc-ph-open-session): (eudc-ph-close-session): * net/eudc.el (eudc-save-options): * language/thai-word.el (thai-update-word-table): * language/japan-util.el (japanese-string-conversion): * international/titdic-cnv.el (tsang-quick-converter) (ziranma-converter, ctlau-converter): * international/mule-cmds.el (describe-language-environment): * international/ja-dic-cnv.el (skkdic-convert-okuri-ari) (skkdic-convert-postfix, skkdic-convert-prefix): (skkdic-convert-okuri-nasi, skkdic-convert): * emacs-lisp/re-builder.el (reb-update-overlays): * emacs-lisp/pp.el (pp-to-string, pp-display-expression): * emacs-lisp/gulp.el (gulp-send-requests): * emacs-lisp/find-gc.el (trace-call-tree): * emacs-lisp/eieio-opt.el (eieio-browse, eieio-describe-class) (eieio-describe-generic): * emacs-lisp/eieio-base.el (eieio-persistent-read): * emacs-lisp/edebug.el (edebug-outside-excursion): * emacs-lisp/debug.el (debugger-make-xrefs): * emacs-lisp/cust-print.el (custom-prin1-to-string): * emacs-lisp/chart.el (chart-new-buffer): * emacs-lisp/authors.el (authors-scan-el, authors-scan-change-log): Use with-current-buffer. * textmodes/artist.el (artist-system): Don't call copy-sequence on a fresh string. * progmodes/idlw-shell.el (easymenu setup): Use dolist.

: #-*- Perl -*-
eval 'exec perl -w -S $0 ${1+"$@"}' # Portability kludge
    if 0;

# Author: Martin Buchholz
# This program is in the public domain.

use strict;
use POSIX;

(my $myName = $0) =~ s@.*/@@; my $usage="
Usage: $myName

Finds DOCSTRING arg mismatches between
formal parameters, docstrings, and lispref texi.

This program is in the public domain.\n";

die $usage if @ARGV;
die $usage unless -r "src/alloc.c" && -d "CVS" && -d "lisp";

my %texi_funtype;
my %texi_arglist;

my %code_funtype;
my %code_arglist;

sub FileContents {
  local $/ = undef;
  open (FILE, "< $_[0]") or die "$_[0]: $!";
  return scalar <FILE>;
}

sub Show_details {
  my ($show_details, $function, $parms, $docstring) = @_;
  if ($show_details) {
    print "function = $function $parms\n$docstring\n", "-" x 70, "\n";
  }
}

sub Check_texi_function {
  my ($function, $funtype, $docstring, @parms) = @_;
  my %docstring_parm;
  my %docstring_word;
  my %arglist_parm;
  my $show_details = 0;

  if (exists $texi_funtype{$function}) {
    print "duplicate texidoc: $function @parms\n";
    return;			# later definition likely bogus package def
  }

  $texi_funtype{$function} = $funtype;
  $texi_arglist{$function} = "@parms";

  foreach my $parm (@parms) {
    next if $parm eq '&optional' || $parm eq '&rest';
    $arglist_parm{$parm} = 1;
  }

  foreach my $parm ($docstring =~ /\@var{([^{}]+)}/g) {
    $docstring_parm{$parm} = 1;
  }

  foreach my $hit ($docstring =~ /[^\`]\`[A-Za-z-]+\'/g)
    {
      print "texi \@code missing: $function: $hit\n";
      $show_details = 1;
    }

  #   (my $raw_docstring = $docstring) =~ s/\@var{[^{}]+}//g;
  #   $raw_docstring =~ s/[^a-zA-Z_-]+/ /g;
  #   foreach my $word (split (' ', $raw_docstring)) {
  #     if ($word =~ /^[A-Z][A-Z-]+$/) {
  #       print "Missing \@var: $function: $word\n";
  #     }
  #   }

  foreach my $parm (keys %docstring_parm) {
    if (! exists $arglist_parm{$parm}) {
      print "bogus texi parm: $function: $parm\n";
      $show_details = 1;
    }
  }

  foreach my $parm (keys %arglist_parm) {
    if (! exists $docstring_parm{$parm}) {
      print "undocumented texi parm: $function: $parm\n";
      $show_details = 1;
    }
  }

  Show_details $show_details, $function, "@parms", $docstring;
}

sub Check_function {
  my ($function, $funtype, $docstring, @parms) = @_;
  my %docstring_parm;
  my %arglist_parm;
  my $show_details = 0;

  if (exists $code_funtype{$function}) {
    print "duplicate codedef: $function @parms\n";
    return;			# later definition likely bogus package def
  }

  $code_funtype{$function} = $funtype;
  $code_arglist{$function} = "@parms";
  #foreach my $parm ($parms =~ /\b[a-z0-9-]{3,}\b/g) {
  #  $arglist_parm{$parm} = 1;
  #}
  foreach my $parm (@parms) {
    next if $parm eq '&optional' || $parm eq '&rest';
    $arglist_parm{$parm} = 1;
  }
  my $doc_tmp = $docstring;
  $doc_tmp =~ s/[^A-Za-z0-9_-]/ /g;
  foreach my $parm (split (' ', $doc_tmp)) {
    if ($parm =~ /^[A-Z][A-Z0-9-]*$/) {
      next if $parm =~ /I18N/;
      next if $parm =~ /M17N/;
      $parm =~ tr[A-Z][a-z];
      $docstring_parm{$parm} = 1;
    }
  }
  #  foreach my $parm ($docstring =~ /\b[A-Z0-9-]{1,}\b/g) {
  #    next if $parm =~ /-$/;
  #    $parm =~ tr[A-Z][a-z];
  #    $docstring_parm{$parm} = 1;
  #  }
  foreach my $parm (keys %docstring_parm) {
    next if $parm eq 'tty';
    next if $parm eq 'fsf';
    next if $parm eq 'note';
    next if $parm eq 'warning';
    next if $parm eq 'bug';
    next if $parm eq 'ascii';
    next if $parm eq 'iso';
    next if $parm eq 'and';
    next if $parm eq 'absolutely';
    next if $parm eq 'doc';
    next if $parm eq 'user';
    next if $parm eq 'not';
    next if $parm eq 'must';
    next if $parm eq 'nil';
    next if $parm eq 'esc';
    next if $parm eq 'lfd';
    next if $parm eq 'gpm';
    next if $parm eq 'primary';
    next if $parm eq 'secondary';
    next if $parm eq 'clipboard';
    next if length $parm < 3;
    if (! exists $arglist_parm{$parm}) {
      print "bogus parm: $function: $parm\n";
      $show_details = 1;
    }
  }
  foreach my $parm (keys %arglist_parm) {
    if (! exists $docstring_parm{$parm}) {
      print "Undocumented parm: $function: $parm\n";
      $show_details = 1;
    }
  }

  if ($docstring !~ /[\]}!\)\.]\s*\Z/m &&
      $docstring =~ /\S/ &&
      $docstring !~ /Keywords supported/)
    {
      print "Missing trailing period: $function\n";
      $show_details = 1;
    }

  if (exists $texi_arglist{$function}
      and "@parms" ne $texi_arglist{$function}
      and not ("@parms" eq 'int nargs Lisp-Object *args'
	       && $texi_arglist{$function} =~ /&rest/)) {
    my @texi_parms = split (' ', $texi_arglist{$function});
    my @a = ("@parms" =~ /&optional/g);
    my @b = ("@parms" =~ /&rest/g);
    my @c = ("@texi_parms" =~ /&optional/g);
    my @d = ("@texi_parms" =~ /&rest/g);
    if (@parms != @texi_parms
	|| (@a != @c) || (@b != @d)) {
      print "serious mismatch: $function: @parms --- @texi_parms\n";
    } else {
      print "texi mismatch: $function: @parms --- $texi_arglist{$function}\n";
    }
    $show_details = 1;
  }

  if (exists $texi_funtype{$function}
      && $texi_funtype{$function} ne $funtype) {
    print "interactiveness mismatch: $function: $funtype --- $texi_funtype{$function}\n";
    $show_details = 1;
  }

  Show_details $show_details, $function, "@parms", $docstring;
}

my $lisprefdir;
if    (-d "man/lispref") { $lisprefdir = "man/lispref"; }
elsif (-d "lispref") { $lisprefdir = "lispref"; }
else { die "Can't find lispref texi directory.\n"; }

open (FIND, "find $lisprefdir -name '*.texi' -print |") or die;
while (my $file = <FIND>) {
  my @matches = ((FileContents $file) =~
		 /\@(def(?:fn|un))([^\n]+)\n(.*?)\n\@end def(?:un|fn)/sgo);
  #		 /^\@(def(?:un|fn))\s+(.*)\n([.|\n]*?)^\@end def(?:un|fn)\n/mgo);
  while (@matches) {
    my ($defform, $defn, $docstring) = splice (@matches, 0, 3);
    #print "defform = $defform\n";
    #print "defn = $defn\n";
    #print "docstring = $docstring\n";
    my ($function, @parms, $funtype);
    if ($defform eq 'defun') {
      ($funtype, $function, @parms) = ('Function', split (' ', $defn));
    } else {
      die unless $defform eq 'deffn';
      ($funtype, $function, @parms) = split (' ', $defn);
    }
    next if $funtype eq '{Syntax' or $funtype eq '{Prefix';

    Check_texi_function $function, $funtype, $docstring, @parms;
  }
}

open (FIND, "find src -name '*.c' -print |") or die;
while (my $file = <FIND>) {
  my @matches =
    ((FileContents $file) =~
     /\bDEFUN\s*\(\s*\"((?:[^\\\"]|\\.)+)\"\s*,\s*\S+\s*,\s*(\S+)\s*,\s*(\S+)\s*,\s*((?:0|\"(?:(?:[^\\\"]|\\.)*)\"))\s*,\s*\/\*(.*?)\*\/\s*\(([^()]*)\)\)/sgo);
  while (@matches) {
    my ($function, $minargs, $maxargs, $interactive, $docstring, $parms) = splice (@matches, 0, 6);
    $docstring =~ s/^\n+//s;
    $docstring =~ s/\n+$//s;
    $parms =~ s/,/ /g;
    my @parms = split (' ',$parms);
    for (@parms) { tr/_/-/; s/-$//; }
    if ($parms !~ /Lisp_Object/) {
      if ($minargs < @parms) {
	if ($maxargs =~ /^\d+$/) {
	  die unless $maxargs eq @parms;
	  splice (@parms, $minargs, 0, '&optional');
	}
      }
    }
    my $funtype = ($interactive =~ /\"/ ? 'Command' : 'Function');
    Check_function $function, $funtype, $docstring, @parms;
  }
}

my @pkgs;
if (-d "../xemacs-packages") {
  @pkgs = qw (libs/edebug libs/xemacs-base comm/eudc oa/edit-utils);
} else {
  @pkgs = ();
}
for (@pkgs) { s@^@../xemacs-packages/@; }
open (FIND, "find lisp @pkgs -name '*.el' -print |") or die;
while (my $file = <FIND>) {
  my $contents = FileContents $file;
  $contents =~ s/(?:\s|;);.*//mog;
  my @matches =
    ($contents =~
     /\((def(?:un|subst|macro))\s+(\S+)\s+\(([^()]*)\)\s+\"((?:[^\\\"]|\\.)+)\"(.*?)\)/sgo);
  while (@matches) {
    my ($defform, $function, $parms, $docstring, $code_fragment) = splice (@matches, 0, 5);

    my $funtype =
      $defform eq 'defmacro' ? 'Macro' :
	$code_fragment =~ /^\s*\(interactive\b/so ? 'Command' :
	  'Function';

    $docstring =~ s/^\n+//s;
    $docstring =~ s/\n+$//s;

    my @parms = split (' ', $parms);

    Check_function $function, $funtype, $docstring, @parms;
  }
}

open (FIND, "find lisp @pkgs -name '*.el' -print |") or die;
while (my $file = <FIND>) {
  my $contents = FileContents $file;
  $contents =~ s/(?:\s|;);.*//mog;

  my @matches = ($contents =~ /^\((?:defalias|fset|define-function)\s+\'([A-Za-z0-9_-]+)\s+\'([A-Za-z0-9_-]+)/mog);
  while (@matches) {
    my ($alias, $aliasee) = splice (@matches, 0, 2);
    print "alias $alias aliasee $aliasee\n";
    if (exists $code_funtype{$aliasee}) { $code_funtype{$alias} = $code_funtype{$aliasee}; }
    if (exists $code_arglist{$aliasee}) { $code_arglist{$alias} = $code_arglist{$aliasee}; }
  }
}

foreach my $fun (sort keys %texi_funtype) {
  if (not exists $code_funtype{$fun}) {
    print "nuke-this-doc: $fun $texi_funtype{$fun}\n";
  }
}

# arch-tag: e75331f5-5d1b-4393-ad5b-b0f87b5d47b0