bugGNU Octave - Bugs: bug #59380, documentation for cast function...

 
 

bug #59380: documentation for cast function doesn't imply it returns a value

Submitter:  None
Submitted:  Thu 29 Oct 2020 02:10:29 PM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  DuarteArribas Originator Email:  -email is unavailable-
Open/Closed:  * Closed Release:  * dev
Operating System:  * Any Fixed Release:  None
Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 06 Apr 2022 03:27:07 AM UTC, comment #4: 

I rewrote the documentation for all m-files to have a return value when there is one.  See changeset http://hg.savannah.gnu.org/hgweb/octave/rev/5d3faba0342e.

Marking bug as Fixed and closing report.

Rik <rik5>
Group administrator
Thu 29 Oct 2020 03:14:39 PM UTC, comment #3: 

This is probably a general problem with the documentation.  Taking a look at sind.m I see


-- sind (X)
     Compute the sine for each element of X in degrees.


By Octave conventions, it is understood that X is not changed and that sind returns a value.  It would be a big shift, but it would be clearer to show


-- Y = sind (X)
     Compute the sine for each element of X in degrees.


where the return value is explicitly shown in the documentation.

If the Octave project wants to take this step it will be a large one.  For that reason, I'm changing the Release from 6.0.92 to dev.  This can't be fixed with the limited amount of time before the 6.1 release.

Rik <rik5>
Group administrator
Thu 29 Oct 2020 03:03:02 PM UTC, comment #2: 

This might be just about documentation.  The documentation begins:


-- cast (VAL, "TYPE")
     Convert VAL to data type TYPE.


It would be easy enough to show that a value is returned with something like


-- NEWVAL = cast (VAL, "TYPE")


Rik <rik5>
Group administrator
Thu 29 Oct 2020 02:38:17 PM UTC, comment #1: 

The problem is not clear. Are you saying that the new users are expecting the original variable to be cast to the new type in-place? If so, Octave and Matlab have always been pass-by-value not pass-by-reference so that is not specific to the casting functions.

Anonymous
Thu 29 Oct 2020 02:10:29 PM UTC, original submission:  

The function cast documented at https://octave.org/doc/v4.2.1/Built_002din-Data-Types.html doesn't imply it returns a value, hence the confusion of some octave newbies, that don't know the normal behavior of octave

Anonymous

 

(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 rik5 (Posted a comment)
  • -email is unavailable- added by None (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.

     

    Follow 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-04-06 rik5 StatusNone Fixed
        Open/ClosedOpen Closed
    2020-10-29 rik5 SummaryFunction cast doesn't imply it returns a value documentation for cast function doesn't imply it returns a value
    2020-10-29 rik5 Release6.0.92 dev

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code