[Octave-bug-tracker] [bug #45747] octave-image: Inconsistent argument names in doc strings

[Rafael Laboissiere]

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/