[postgis-devel] [PostGIS] #1240: [raster] ST_Addband() should be in the "Raster Constructors" part of the documentation

[PostGIS]

#1240: [raster] ST_Addband() should be in the "Raster Constructors" part of the
documentation
----------------------------+-----------------------------------------------
  Reporter:  pracine        |       Owner:  robe         
      Type:  enhancement    |      Status:  closed       
  Priority:  medium         |   Milestone:  PostGIS 2.0.0
 Component:  documentation  |     Version:               
Resolution:  fixed          |    Keywords:               
----------------------------+-----------------------------------------------

Comment(by pracine):

 Replying to [comment:8 robe]:
 > Hmm those don't really fit in any other place (geometry) so I guess I'll
 have to rethink my definition of accessors.
 >
 > How about we just get rid of Raster Band Accessors section and combine
 it so its
 >
 > Raster Accessors. I never liked that separation. Because a Band does not
 exist as a bonafide object.  It would be like having a Patches accessors
 or InteriorRingN accessors section.  Too much minutiae.
 >
 > When you do ST_Band() -- YOU ARE creating a new raster like it or not.
 You are taking a subset of your raster and making a new raster.  It's not
 even a pointer its a copy of the sections of your original raster.

 When you are doing ST_SRID() -- YOU ARE creating a new number like it or
 not.

 To me accessors are getters of existing objects part of others.
 Constructors starts from nothing which was this kind of object before
 (geometries from numbers, rasters from numbers).

 Also sometimes you speak about "Settors" and sometimes about "Editors". To
 me all "set" functions should just be "Editors" and "get" function (that
 get an existing part of an object without modifying it) should be
 "Accessors". Then you get different levels of access: raster, band, pixel
 or specific categories (like the ones for stats, processing or outputs).

 I would also rather call "Outputs" "Converters"...

 What about definitions like this:

 Management - Functions to manage the database structure or get info about
 non geographical objects.

 XXX Construction - Functions to create new XXX.

 XXX Property - Functions returning XXX properties (or parts of XXX
 properties) (implying or not a computation - commonly knows as getters).

 XXX Edition - Functions to edit XXX properties.

 XXX Process - Functions to tranform or process XXX objects (or parts of
 XXX objects) into new XXX objects.

 XXX Conversion - Functions to convert XXX objects into other equivalent
 objects.

 XXX Operators - Spatial relationship operators.

 XXX Spatial Relationship - Boolean functions returning the status of a
 spatial relationship.

 XXX Metric - Functions returning a measure.

 XXX Statistic - Function returning computed statistics related to a
 geographical object (or a part of a geographical object).

 Some specific sections are possible for groups of function doing specific
 things ("Linear referencing").

 XXX could be replaced with "Geometry", "Geography", "Raster", "Raster
 Band" or "Raster Pixel". I don't know how you managed the geography type
 though.

 The "XXX Property" section could be splitted into "XXX Property" and "XXX
 Derived Property" for properties implying a computation of some sort like
 ST_Boundary(), ST_IsClosed(), ST_IsValid(), etc... But then it would
 become hard to distinguish them from the Process functions...

 I would drop the word "Function" from the sections titles as they are all
 functions anyway and we know it (now sometimes it's there and sometimes
 it's not there).

 I would guess "Operators" forced you to give "ors" names to every sections
 (like "EditORS" - I don't know the specific name of that kind of name) but
 since it does not work in many cases (Spatial RelationshipORS!!!) I would
 rather keep this form only for "Operators" and give category like named to
 sections like I did above.

 With those definitions applied to the "PostGIS Reference" section:

 -The Spatial relationship functions would be separated from the
 Measurements ones - which I think is very good.
 -All the ST_XMin, ST_YMin, ST_XMax, etc. miscellaneous functions should go
 in the "XXX Property" since they are like those implying a computation.
 -Find_SRID() should go in the "Management" section.
 -Actually all the "Miscellaneous Functions" should find a place somewhere
 in the "Management" or the "XXX Property" section if you accept that some
 of the "XXX Property" are computed (e.g. ST_MemSize() should go in the
 "XXX Property" section).
 -A better analysis would probably determine other changes.

 I think the harder things to distinguish are "Process" functions from some
 "derived" Properties functions (e.g. ST_ConcaveHull() VS ST_Boundary() and
 ST_NumGeometries() VS ST_Dump()). We might want to precise both
 definitions to solve this.

 I would add the section definition in the doc itself so don't lose them
 and we can refer to them to identify a misclassification.

 Sorry to open a Pendora's box but I always found that the classification
 was a bit lame...

-- 
Ticket URL: <http://trac.osgeo.org/postgis/ticket/1240#comment:9>
PostGIS <http://trac.osgeo.org/postgis/>
The PostGIS Trac is used for bug, enhancement & task tracking, a user and developer wiki, and a view into the subversion code repository of PostGIS project.