# HG changeset patch
# User Rik <rik@octave.org>
# Date 1393625081 28800
# Node ID 04b4fb217b1a2cf3c47698e6e4fb2c08e4958d7c
# Parent  186ea1c2bbd4bbb8d20e3ac1a3854360def5b8dd
doc: Improve documentation strings in parse-tree directory.

* lex.ll (F__display_tokens__): Add seealso reference.
* lex.ll (F__token_count__): Add seealso reference.
* lex.ll (F__lexer_debug_flag__): Document function.

* oct-parse.in.yy (Fautoload): Add additional calling form.  Rephrase
several sentences.
* oct-parse.in.yy (Fmfilename): Make single sentence description stand
apart from the rest of documentation.
* oct-parse.in.yy (Fsource): Make single sentence description stand
apart from the rest of documentation.  Add seealso link to 'run'.
* oct-parse.in.yy (Fbuiltin): Change type to "Built-in Function" from
"Loadable Function".
* oct-parse.in.yy (Feval): Rephrase several sentences.  Add programming
note suggesting the use of alternatives like try/catch or unwind_protect.
* oct-parse.in.yy (F__parser_debug_flag__): Document function.

* pt-mat.cc (Fstring_fill_char): Use semicolon in place of period for
stronger idea linkage.

diff -r 186ea1c2bbd4 -r 04b4fb217b1a libinterp/parse-tree/lex.ll
--- a/libinterp/parse-tree/lex.ll	Fri Feb 28 13:50:08 2014 -0800
+++ b/libinterp/parse-tree/lex.ll	Fri Feb 28 14:04:41 2014 -0800
@@ -1781,6 +1781,7 @@
 @deftypefn {Built-in Function} {} __display_tokens__ ()\n\
 Query or set the internal variable that determines whether Octave's\n\
 lexer displays tokens as they are read.\n\
+@seealso{__lexer_debug_flag__, __token_count__}\n\
 @end deftypefn")
 {
   return SET_INTERNAL_VARIABLE (display_tokens);
@@ -1789,7 +1790,8 @@
 DEFUN (__token_count__, , ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} __token_count__ ()\n\
-Number of language tokens processed since Octave startup.\n\
+Return the number of language tokens processed since Octave startup.\n\
+@seealso{__lexer_debug_flag__, __display_tokens__}\n\
 @end deftypefn")
 {
   return octave_value (Vtoken_count);
@@ -1797,8 +1799,11 @@
 
 DEFUN (__lexer_debug_flag__, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {@var{old_val} =} __lexer_debug_flag__ (@var{new_val}))\n\
-Undocumented internal function.\n\
+@deftypefn  {Built-in Function} {@var{val} =} __lexer_debug_flag__ ()\n\
+@deftypefnx {Built-in Function} {@var{old_val} =} __lexer_debug_flag__ (@var{new_val})\n\
+Query or set the internal flag that determines whether Octave's lexer prints\n\
+debug information as it processes an expression.\n\
+@seealso{__display_tokens__, __token_count__, __parse_debug_flag__}\n\
 @end deftypefn")
 {
   octave_value retval;
diff -r 186ea1c2bbd4 -r 04b4fb217b1a libinterp/parse-tree/oct-parse.in.yy
--- a/libinterp/parse-tree/oct-parse.in.yy	Fri Feb 28 13:50:08 2014 -0800
+++ b/libinterp/parse-tree/oct-parse.in.yy	Fri Feb 28 14:04:41 2014 -0800
@@ -3709,13 +3709,14 @@
 
 DEFUN (autoload, args, ,
   "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {} autoload (@var{function}, @var{file})\n\
-@deftypefnx {Built-in Function} {} autoload (@dots{}, @asis{\"remove\"})\n\
+@deftypefn  {Built-in Function} {@var{autoload_map} =} autoload ()\n\
+@deftypefnx {Built-in Function} {} autoload (@var{function}, @var{file})\n\
+@deftypefnx {Built-in Function} {} autoload (@dots{}, \"remove\")\n\
 Define @var{function} to autoload from @var{file}.\n\
 \n\
 The second argument, @var{file}, should be an absolute file name or\n\
 a file name in the same directory as the function or script from which\n\
-the autoload command was run.  @var{file} should not depend on the\n\
+the autoload command was run.  @var{file} @emph{should not} depend on the\n\
 Octave load path.\n\
 \n\
 Normally, calls to @code{autoload} appear in PKG_ADD script files that\n\
@@ -3729,7 +3730,7 @@
 \n\
 @noindent\n\
 will load the function @code{foo} from the file @code{bar.oct}.  The above\n\
-usage when @code{bar.oct} is not in the same directory or usages such as\n\
+usage when @code{bar.oct} is not in the same directory, or usages such as\n\
 \n\
 @example\n\
 autoload (\"foo\", file_in_loadpath (\"bar.oct\"))\n\
@@ -3740,7 +3741,7 @@
 \n\
 With no arguments, return a structure containing the current autoload map.\n\
 \n\
-If a third argument @asis{'remove'} is given, the function is cleared and\n\
+If a third argument @qcode{\"remove\"} is given, the function is cleared and\n\
 not loaded anymore during the current Octave session.\n\
 \n\
 @seealso{PKG_ADD}\n\
@@ -3938,11 +3939,12 @@
 @deftypefn  {Built-in Function} {} mfilename ()\n\
 @deftypefnx {Built-in Function} {} mfilename (\"fullpath\")\n\
 @deftypefnx {Built-in Function} {} mfilename (\"fullpathext\")\n\
-Return the name of the currently executing file.  At the top-level,\n\
-return the empty string.  Given the argument @qcode{\"fullpath\"},\n\
-include the directory part of the file name, but not the extension.\n\
-Given the argument @qcode{\"fullpathext\"}, include the directory part\n\
-of the file name and the extension.\n\
+Return the name of the currently executing file.\n\
+\n\
+When called from outside an m-file return the empty string.  Given the\n\
+argument @qcode{\"fullpath\"}, include the directory part of the file name,\n\
+but not the extension.  Given the argument @qcode{\"fullpathext\"}, include\n\
+the directory part of the file name and the extension.\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -4004,9 +4006,11 @@
 DEFUN (source, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} source (@var{file})\n\
-Parse and execute the contents of @var{file}.  This is equivalent to\n\
-executing commands from a script file, but without requiring the file to\n\
-be named @file{@var{file}.m}.\n\
+Parse and execute the contents of @var{file}.\n\
+\n\
+This is equivalent to executing commands from a script file, but without\n\
+requiring the file to be named @file{@var{file}.m}.\n\
+@seealso{run}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -4176,7 +4180,7 @@
 
 DEFUN (builtin, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Loadable Function} {[@dots{}] =} builtin (@var{f}, @dots{})\n\
+@deftypefn {Built-in Function} {[@dots{}] =} builtin (@var{f}, @dots{})\n\
 Call the base function @var{f} even if @var{f} is overloaded to\n\
 another function for the given type signature.\n\
 \n\
@@ -4343,14 +4347,14 @@
 The string @var{try} is evaluated in the current context,\n\
 so any results remain available after @code{eval} returns.\n\
 \n\
-The following example makes the variable @var{A} with the approximate\n\
-value 3.1416 available.\n\
+The following example creates the variable @var{A} with the approximate\n\
+value of 3.1416 in the current workspace.\n\
 \n\
 @example\n\
 eval (\"A = acos(-1);\");\n\
 @end example\n\
 \n\
-If an error occurs during the evaluation of @var{try} the @var{catch}\n\
+If an error occurs during the evaluation of @var{try} then the @var{catch}\n\
 string is evaluated, as the following example shows:\n\
 \n\
 @example\n\
@@ -4362,9 +4366,11 @@
 @end group\n\
 @end example\n\
 \n\
-Consider using try/catch blocks instead if you are only using @code{eval}\n\
-as an error-capturing mechanism rather than for the execution of arbitrary\n\
-code strings.\n\
+Programming Note: if you are only using @code{eval} as an error-capturing\n\
+mechanism, rather than for the execution of arbitrary code strings,\n\
+Consider using try/catch blocks or unwind_protect/unwind_protect_cleanup\n\
+blocks instead.  These techniques have higher performance and don't introduce\n\
+the security considerations that the evaluation of arbitrary code does.\n\
 @seealso{evalin}\n\
 @end deftypefn")
 {
@@ -4575,8 +4581,11 @@
 
 DEFUN (__parser_debug_flag__, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {@var{old_val} =} __parser_debug_flag__ (@var{new_val}))\n\
-Undocumented internal function.\n\
+@deftypefn  {Built-in Function} {@var{val} =} __parser_debug_flag__ ()\n\
+@deftypefnx {Built-in Function} {@var{old_val} =} __parser_debug_flag__ (@var{new_val})\n\
+Query or set the internal flag that determines whether Octave's parser prints\n\
+debug information as it processes an expression.\n\
+@seealso{__lexer_debug_flag__}\n\
 @end deftypefn")
 {
   octave_value retval;
diff -r 186ea1c2bbd4 -r 04b4fb217b1a libinterp/parse-tree/pt-mat.cc
--- a/libinterp/parse-tree/pt-mat.cc	Fri Feb 28 13:50:08 2014 -0800
+++ b/libinterp/parse-tree/pt-mat.cc	Fri Feb 28 14:04:41 2014 -0800
@@ -1374,7 +1374,7 @@
 @deftypefnx {Built-in Function} {@var{old_val} =} string_fill_char (@var{new_val})\n\
 @deftypefnx {Built-in Function} {} string_fill_char (@var{new_val}, \"local\")\n\
 Query or set the internal variable used to pad all rows of a character\n\
-matrix to the same length.  It must be a single character.  The default\n\
+matrix to the same length; It must be a single character.  The default\n\
 value is @qcode{\" \"} (a single space).  For example:\n\
 \n\
 @example\n\