[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Octave-bug-tracker] [bug #45747] octave-image: Inconsistent argument na
From: |
Rafael Laboissiere |
Subject: |
[Octave-bug-tracker] [bug #45747] octave-image: Inconsistent argument names in doc strings |
Date: |
Thu, 13 Aug 2015 20:42:13 +0000 |
User-agent: |
Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36 |
URL:
<http://savannah.gnu.org/bugs/?45747>
Summary: octave-image: Inconsistent argument names in doc
strings
Project: GNU Octave
Submitted by: rlaboiss
Submitted on: Thu 13 Aug 2015 08:42:12 PM GMT
Category: Octave Forge Package
Severity: 3 - Normal
Priority: 5 - Normal
Item Group: Incorrect Documentation
Status: None
Assigned to: None
Originator Name:
Originator Email:
Open/Closed: Open
Discussion Lock: Any
Release: other
Operating System: Any
_______________________________________________________
Details:
I am reporting below some comments made by Francesco Potortì in the context
of Bug#794780 <http://bugs.debian.org/794780>, filed against the Debian
pacakge octave-image. There are apparently incosistencies in the way
arguments are named in functions cp2tform, maketform, tformfwd, and tforminv.
I am transcribing almost verbatim what Francesco wrote. I did not check
carefully his claims. Please, feel free to close this bug report if you think
the comments are not relevant.
Rafael Laboissière
=================================================
From: Francesco Potortì
Date: 2015-08-13
-- Function File: T = cp2tform (RW_PT, AP_PT, TRANSTYPE)
-- Function File: T = cp2tform (RW_PT, AP_PT, TRANSTYPE, OPT)
Returns a transformation structure T (see "help maketform" for the
form of the structure) that can be further used to transform
coordinates from one space (here denoted "RW" for "real world") to
another (here denoted "AP" for "apparent"). The transform is
As you can read, the two reference systems are called here "real world" and
"apparent".
-- Function File: T = maketform (TTYPE, TMAT)
-- Function File: T = maketform (TTYPE, INC, OUTC)
-- Function File: T = maketform ("custom", NDIMS_IN, NDIMS_OUT,
FORWARD_FCN, INVERSE_FCN, TDATA)
Create structure for spatial transformations.
Here no explicit name is given to the two reference systems, but from the
formal arguments it is apparent that they are intended as "in" and "out".
-- Function File: [UV] = tformfwd (T, XY)
-- Function File: [U, V] = tformfwd (T, X, Y)
Given to dimensionnal coordinates from one space, returns two
dimensionnal coordinates in the other space, as defined in the
transform structure T. Input and output coordinates may be gigen
either as a n-by-2 arrays, or as two n-by-1 vectors.
Here the two reference systems are just anonymous, so no semantic is even
suggested, and they are called "one" and "the other".
So we have three different naming conventions for three functions which are
strictly related. Since maketform is the basis function, and the one that
choses the naming of the fields in the Tform, probebaly the "in" and "out"
convention should be used in all description strings.
Now that I notice it, the tforminv function has the same exact description as
the tformfwd function, which makes no sense. The typos are the same, and
besides it should at least mention that while the tformfwd uses the
"forward_fcn" matrix inside the Tform, tforminv uses the "inverse_fcn" matrix
in the Tform.
_______________________________________________________
Reply to this item at:
<http://savannah.gnu.org/bugs/?45747>
_______________________________________________
Message sent via/by Savannah
http://savannah.gnu.org/
- [Octave-bug-tracker] [bug #45747] octave-image: Inconsistent argument names in doc strings,
Rafael Laboissiere <=