octave-bug-tracker
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Octave-bug-tracker] [bug #51933] Documentation of function rand and oth


From: Ernst Reissner
Subject: [Octave-bug-tracker] [bug #51933] Documentation of function rand and others
Date: Mon, 4 Sep 2017 09:33:35 -0400 (EDT)
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:51.0) Gecko/20100101 Firefox/51.0

URL:
  <http://savannah.gnu.org/bugs/?51933>

                 Summary: Documentation of function rand and others
                 Project: GNU Octave
            Submitted by: ernstreissner
            Submitted on: Mon 04 Sep 2017 01:33:33 PM UTC
                Category: Documentation
                Severity: 3 - Normal
                Priority: 5 - Normal
              Item Group: Documentation
                  Status: None
             Assigned to: None
         Originator Name: 
        Originator Email: 
             Open/Closed: Open
         Discussion Lock: Any
                 Release: dev
        Operating System: Any

    _______________________________________________________

Details:


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, 





    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?51933>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/




reply via email to

[Prev in Thread] Current Thread [Next in Thread]