bugGNU Octave - Bugs: bug #51933, Documentation of function rand and...

 
 

bug #51933: Documentation of function rand and others

Submitter:  Ernst Reissner <ernstreissner>
Submitted:  Mon 04 Sep 2017 01:33:33 PM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
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
   

Tue 05 Sep 2017 02:27:05 AM UTC, comment #2: 

Confirmed.  If you can prepare a patch I can review.

Rik <rik5>
Group administrator
Mon 04 Sep 2017 01:46:11 PM UTC, comment #1: 

Ah i made a mistake:
rand works only with CLASS=double or single,
which is another difference to eye
which works for integer types like uint64
and even for 'logical' type.

But this is another reason not just to write,
that the arguments are as those for eye. !!!!

Ernst Reissner <ernstreissner>
Mon 04 Sep 2017 01:33:33 PM UTC, original submission:  


The documentation of function rand is incomplete.
In addition it is outdated, because matlab moved a little bit.
I suggest to update documentation first
before, somewhere in future upgrade for sake of matlab compatibility.

I think, a sentence like

The arguments are handled the same as the arguments for `eye'.


is not what the user wants to read, it should be more explicit,
and it should be correct.

In detail:
1.
The case rand() without argument behaves like rand(1)
which is not documented.
This is like eye().

rand(2,3,4) is documented and is allowed whereas eye(2,3,4) is not (eye is restricted to two arguments maximum).
Accordingly, rand([2,3,4]) is allowed and is the same as rand(2,3,4)

These two cases are not like eye which shows,
that we need a separate description.

The return values are missing in most cases:
so rand(n) must be replaced by m=rand(n).

As documented for eye, the variants

m=rand()
m=rand(M, N, ...)
m=rand([M, N, ...])

are also allowed with additional argument CLASS as

m=rand(CLASS)
m=rand(M, N, ...,CLASS)
m=rand([M, N, ...],CLASS)

What is also missing is an explicit enumeration of the allowed values for CLASS, namely

'double', 'single', 'logical', 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int64', or 'uint64',

in particular: logical!!!!

It does not make sense, to state the variants with seed and state  before all those are described becaues

rand('state','double') does not work!!

So we have to mention first:

m=rand()
m=rand(M, N, ...)
m=rand([M, N, ...])
m=rand(CLASS)
m=rand(M, N, ...,CLASS)
m=rand([M, N, ...],CLASS)


Then one has to describe the variants

V = rand ("state")
rand ("state", V)
rand ("state", "reset")


for which it is really true, that V is a vector
and the other variants have no return value.
What is missing is the documentation for second argument 'reset'
which i found nowhere.

Accordingly for 'seed' replacing 'state'.



For the other variants,

Ernst Reissner <ernstreissner>

 

(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 ernstreissner (Submitted the item)
  • -email is unavailable- added by ernstreissner
  •  

    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 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2017-09-05 rik5 StatusNone Confirmed
    2017-09-04 ernstreissner Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code