changeset 12519:91ccd08fe80c

Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
author Rik <octave@nomad.inbox5.com>
date Fri, 18 Mar 2011 14:38:46 -0700
parents 9f926b9f83cc
children ad05e1547398
files doc/ChangeLog doc/interpreter/basics.txi scripts/ChangeLog scripts/help/get_first_help_sentence.m src/ChangeLog src/help.cc
diffstat 6 files changed, 63 insertions(+), 39 deletions(-) [+]
line wrap: on
line diff
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2010-03-18  Rik  <octave@nomad.inbox5.com>
+
+	* interpreter/basics.txi: Add gen_doc_cache, get_help_text, 
+	get_help_text_from_file, get_first_help_sentence to documentation.
+
 2010-03-17  Rik  <octave@nomad.inbox5.com>
 
 	* interpreter/io.txi: Add fileread to documentation.
--- a/doc/interpreter/basics.txi
+++ b/doc/interpreter/basics.txi
@@ -387,6 +387,18 @@
 
 @DOCSTRING(suppress_verbose_help_message)
 
+The following functions are principally used internally by Octave for
+generating the documentation.  They are documented here for completeness
+and because they may occasionally be useful for users.
+
+@DOCSTRING(gen_doc_cache)
+
+@DOCSTRING(get_help_text)
+
+@DOCSTRING(get_help_text_from_file)
+
+@DOCSTRING(get_first_help_sentence)
+
 @node Command Line Editing
 @section Command Line Editing
 @cindex command-line editing
--- a/scripts/ChangeLog
+++ b/scripts/ChangeLog
@@ -1,3 +1,7 @@
+2010-03-18  Rik  <octave@nomad.inbox5.com>
+
+	* help/get_first_help_sentence.m: Improve docstring.  Add tests.
+
 2010-03-17  Rik  <octave@nomad.inbox5.com>
 
 	* scripts/sparse/svds.m: Fix bug #32818, nonconformant arguments
--- a/scripts/help/get_first_help_sentence.m
+++ b/scripts/help/get_first_help_sentence.m
@@ -17,15 +17,14 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {[@var{retval}, @var{status}] =} get_first_help_sentence (@var{name}, @var{max_len})
-## Return the first sentence of a function help text.
+## @deftypefn  {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@var{name})
+## @deftypefnx {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@var{name}, @var{max_len})
+## Return the first sentence of a function's help text.
 ##
-## The function reads the first sentence of the help text of the function
-## @var{name}.  The first sentence is defined as the text after the function
+## The first sentence is defined as the text after the function
 ## declaration until either the first period (".") or the first appearance of
-## two consecutive end-lines ("\n\n").  The text is truncated to a maximum
-## length
-## of @var{max_len}, which defaults to 80.
+## two consecutive newlines ("\n\n").  The text is truncated to a maximum
+## length of @var{max_len}, which defaults to 80.
 ##
 ## The optional output argument @var{status} returns the status reported by
 ## @code{makeinfo}.  If only one output argument is requested, and @var{status}
@@ -36,23 +35,23 @@
 ## @example
 ## @group
 ## get_first_help_sentence ("get_first_help_sentence")
-## @print{} ans = Return the first sentence of a function help text.
+## @print{} ans = Return the first sentence of a function's help text.
 ## @end group
 ## @end example
 ## @end deftypefn
 
-function [retval, status] = get_first_help_sentence (name, max_len = 80)
+function [text, status] = get_first_help_sentence (name, max_len = 80)
   ## Check input
-  if (nargin == 0)
-    error ("get_first_help_sentence: not enough input arguments");
+  if (nargin < 1 || nargin > 2)
+    print_usage ();
   endif
 
   if (!ischar (name))
-    error ("get_first_help_sentence: first input must be a string");
+    error ("get_first_help_sentence: NAME must be a string");
   endif
 
   if (!isnumeric (max_len) || max_len <= 0 || max_len != round (max_len))
-    error ("get_first_help_sentence: second input must be positive integer");
+    error ("get_first_help_sentence: MAX_LEN must be positive integer");
   endif
 
   ## First, we get the raw help text
@@ -61,11 +60,11 @@
   ## Then, we take action depending on the format
   switch (lower (format))
     case "plain text"
-      [retval, status] = first_sentence_plain_text (help_text, max_len);
+      [text, status] = first_sentence_plain_text (help_text, max_len);
     case "texinfo"
-      [retval, status] = first_sentence_texinfo (help_text, max_len);
+      [text, status] = first_sentence_texinfo (help_text, max_len);
     case "html"
-      [retval, status] = first_sentence_html (help_text, max_len);
+      [text, status] = first_sentence_html (help_text, max_len);
     case "not documented"
       error ("get_first_help_sentence: `%s' is not documented\n", name);
     case "not found"
@@ -80,18 +79,18 @@
 endfunction
 
 ## This function extracts the first sentence from a plain text help text
-function [retval, status] = first_sentence_plain_text (help_text, max_len)
+function [text, status] = first_sentence_plain_text (help_text, max_len)
   ## Extract first line by searching for a period or a double line-end.
-  period_idx = find (help_text == ".", 1);
+  period_idx = find (help_text == '.', 1);
   line_end_idx = strfind (help_text, "\n\n");
-  retval = help_text (1:min ([period_idx(:); line_end_idx(:); max_len; length(help_text)]));
+  text = help_text (1:min ([period_idx(:); line_end_idx(:); max_len; length(help_text)]));
   status = 0;
 endfunction
 
 ## This function extracts the first sentence from a Texinfo help text.
 ## The function works by removing @def* from the texinfo text. After this, we
 ## render the text to plain text using makeinfo, and then extract the first line.
-function [retval, status] = first_sentence_texinfo (help_text, max_len)
+function [text, status] = first_sentence_texinfo (help_text, max_len)
   ## Lines ending with "@\n" are continuation lines, so they should be concatenated
   ## with the following line.
   help_text = strrep (help_text, "@\n", " ");
@@ -141,16 +140,26 @@
   [help_text, status] = __makeinfo__ (help_text, "plain text");
 
   ## Extract first line with plain text method.
-  retval = first_sentence_plain_text (help_text, max_len);
+  text = first_sentence_plain_text (help_text, max_len);
 endfunction
 
 ## This function extracts the first sentence from a html help text.
 ## The function simply removes the tags and treats the text as plain text.
-function [retval, status] = first_sentence_html (help_text, max_len)
+function [text, status] = first_sentence_html (help_text, max_len)
   ## Strip tags
   [help_text, status] = strip_html_tags (help_text);
 
   ## Extract first line with plain text method.
-  retval = first_sentence_plain_text (help_text, max_len);
+  text = first_sentence_plain_text (help_text, max_len);
 endfunction
 
+%!assert (strcmp (get_first_help_sentence('get_first_help_sentence'), "Return the first sentence of a function's help text."));
+
+%% Test input validation
+%!error get_first_help_sentence ()
+%!error get_first_help_sentence (1, 2, 3)
+%!error get_first_help_sentence (1)
+%!error get_first_help_sentence ('ls', 'a')
+%!error get_first_help_sentence ('ls', 0)
+%!error get_first_help_sentence ('ls', 80.1)
+
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2010-03-18  Rik  <octave@nomad.inbox5.com>
+
+	* help.cc (get_help_text, get_help_text_from_file): Improve docstrings.
+
 2011-03-17  John W. Eaton  <jwe@octave.org>
 
 	* ov-float.cc (octave_float_scalar::do_index_op): Widen to float
--- a/src/help.cc
+++ b/src/help.cc
@@ -719,16 +719,11 @@
 
 DEFUN (get_help_text, args, , "-*- texinfo -*-\n\
 @deftypefn {Loadable Function} {[@var{text}, @var{format}] =} get_help_text (@var{name})\n\
-Return the help text of a given function.\n\
+Return the raw help text of function @var{name}.\n\
 \n\
-This function returns the raw help text @var{text} and an indication of\n\
-its format for the function @var{name}.  The format indication @var{format}\n\
-is a string that can be either @t{\"texinfo\"}, @t{\"html\"}, or\n\
+The raw help text is returned in @var{text} and the format in @var{format}\n\
+The format is a string which is one of @t{\"texinfo\"}, @t{\"html\"}, or\n\
 @t{\"plain text\"}.\n\
-\n\
-To convert the help text to other formats, use the @code{makeinfo} function.\n\
-\n\
-@seealso{makeinfo}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -793,16 +788,11 @@
 DEFUN (get_help_text_from_file, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Loadable Function} {[@var{text}, @var{format}] =} get_help_text_from_file (@var{fname})\n\
-Return the help text from the given file.\n\
+Return the raw help text from the file @var{fname}.\n\
 \n\
-This function returns the raw help text @var{text} and an indication of\n\
-its format for the function @var{name}.  The format indication @var{format}\n\
-is a string that can be either @t{\"texinfo\"}, @t{\"html\"}, or\n\
+The raw help text is returned in @var{text} and the format in @var{format}\n\
+The format is a string which is one of @t{\"texinfo\"}, @t{\"html\"}, or\n\
 @t{\"plain text\"}.\n\
-\n\
-To convert the help text to other formats, use the @code{makeinfo} function.\n\
-\n\
-@seealso{makeinfo}\n\
 @end deftypefn")
 {
   octave_value_list retval;