bugGNU Octave - Bugs: bug #65258, Feature Request: provide function...

 
 

bug #65258: Feature Request: provide function prototype as docstring when no documentation exists

Submitter:  Rik <rik5>
Submitted:  Mon 05 Feb 2024 10:43:58 PM UTC
   
 
Category:  Documentation Severity:  1 - Wish
Priority:  3 - Low Item Group:  Feature Request
Status:  Confirmed Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 14 Feb 2024 03:12:24 AM UTC, comment #4: 

I hadn't looked but was wondering what get_help_text might already be parsing the file to be able to do that. then it could just continue to return [text, status] with text containing the function line

Nicholas Jankowski <nrjank>
Group Member
Wed 14 Feb 2024 02:04:48 AM UTC, comment #3: 

I was imagining that it could be generated from the parse tree because that would guarantee a uniform presentation.  But, maybe it is just way easier to grab the line with keyword function on it, clean it up with a few regexp, and then store it as the docstring for the function.

Rik <rik5>
Group administrator
Wed 14 Feb 2024 12:25:22 AM UTC, comment #2: 

For .m file functions, my plan was to either grab the function text from the file when parsing or generate it from the parse tree.

I don't think we need to worry about what to do for built-in functions because all the ones we care to document should have doc strings.

Same for .oct file functions.  If you want to have something useful displayed, document your function.  There's no way we can automatically generate that info from a DEFUN or MexFunction declaration.

John W. Eaton <jwe>
Group administrator
Tue 13 Feb 2024 11:41:02 PM UTC, comment #1: 

was looking at help for this one.  it's easy enough to copy the 'which' line into the block that currently generates the error, but how would you pull the function definition? not sure of any functions that give you the function meta data like that, or enough pieces to generate a string from.  parse the file itself until you find the first 'function' line?

Nicholas Jankowski <nrjank>
Group Member
Mon 05 Feb 2024 10:43:58 PM UTC, original submission:  

This is a very small thing.  When a programmer tries help() on a function without documentation Octave emits an error that the function is undocumented.  Matlab, however, prints the function prototype which might be at least mildly useful to the programmer.

Here is a simple m-file no_doc_fcn.m that shows what I'm looking for


function y = no_doc_fcn (arg1, arg2, arg3)
end


And when I try using help() I get


octave:1> help no_doc_fcn
error: help: 'no_doc_fcn' is not documented


What would be nice is something like


'no_doc_fcn' is a function from the file /home/xxx/no_doc_fcn.m

  y = no_doc_fcn (arg1, arg2, arg3)



Rik <rik5>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by nrjank (Posted a comment)
  • -email is unavailable- added by rik5 (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follows 1 latest change.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-02-05 rik5 Priority5 - Normal 3 - Low

    Back to the top

    Powered by Savane 3.12.
    Corresponding source code