[Plplot-cvs] SF.net SVN: plplot:[11353] trunk/src/plsym.c

[<ai...@us...>]

Revision: 11353
          http://plplot.svn.sourceforge.net/plplot/?rev=11353&view=rev
Author:   airwin
Date:     2010-11-28 18:40:34 +0000 (Sun, 28 Nov 2010)

Log Message:
-----------
Doxygen documentation of plstring, plsym, plpoin, and plpoin3.

Modified Paths:
--------------
    trunk/src/plsym.c

Modified: trunk/src/plsym.c
===================================================================
--- trunk/src/plsym.c	2010-11-26 18:18:05 UTC (rev 11352)
+++ trunk/src/plsym.c	2010-11-28 18:40:34 UTC (rev 11353)
@@ -29,6 +29,11 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 //
 
+//! @file
+//!
+//! Point-, symbol-, and string-plotting routines.
+//!
+
 #ifndef __PLSYM_H__
 #define __PLSYM_H__
 
@@ -78,13 +83,18 @@
 plhrsh2( PLINT ch, PLINT x, PLINT y );
 
 //--------------------------------------------------------------------------
-// void plstring()
-//
-// Prints out the same string repeatedly at the n points in world
-// coordinates given by the x and y arrays.  Supersedes plpoin and
-// plsymbol for the case where text refers to a unicode glyph either
-// directly as UTF-8 or indirectly via the standard text escape
-// sequences allowed for PLplot input strings.
+//! Plot glyphs (normally just one of them) at the specified
+//! coordinates.  This function largely supersedes plpoin and plsym
+//! because many(!) more glyphs are accessible with plstring.  The
+//! glyph is specified with a PLplot user string.  As with plmtex and
+//! plptex, the user string can contain FCI escapes to determine the
+//! font, UTF-8 code to determine the glyph or else PLplot escapes for
+//! Hershey or unicode text to determine the glyph.
+//! @param n : number of points in x and y arrays.
+//! @param x : array of X coordinates of points.
+//! @param y : array of Y coordinates of points.
+//! @param string : PLplot user string corresponding to the glyph to
+//! be plotted at each of the n points.
 //--------------------------------------------------------------------------
 
 void
@@ -98,9 +108,13 @@
 }
 
 //--------------------------------------------------------------------------
-// void plsym()
-//
-// Plots array y against x for n points using Hershey symbol "code".
+//! Plot a glyph at the specified points.  This function is largely
+//! superseded by plstring which gives access to many(!) more glyphs.
+//! @param n : number of points in x and y arrays.
+//! @param x : pointer to an array with X coordinates of points.
+//! @param y : pointer to an array with Y coordinates of points.
+//! @param code : Hershey symbol code corresponding to a glyph to be
+//! plotted at each of the n points.
 //--------------------------------------------------------------------------
 
 void
@@ -128,16 +142,23 @@
 }
 
 //--------------------------------------------------------------------------
-// void plpoin()
-//
-// Plots array y against x for n points using ASCII code "code".
-//
-// code=-1 means try to just draw a point.  Right now it's just a move and
-// a draw at the same place.  Not ideal, since a sufficiently intelligent
-// output device may optimize it away, or there may be faster ways of
-// doing it.  This is OK for now, though, and offers a 4X speedup over
-// drawing a Hershey font "point" (which is actually diamond shaped and
-// therefore takes 4 strokes to draw).
+//! Plot a glyph at the specified points.  This function is largely
+//! superseded by plstring which gives access to many(!) more glyphs.
+//! code=-1 means try to just draw a point.  Right now it's just a
+//! move and a draw at the same place.  Not ideal, since a
+//! sufficiently intelligent output device may optimize it away, or
+//! there may be faster ways of doing it.  This is OK for now, though,
+//! and offers a 4X speedup over drawing a Hershey font "point" (which
+//! is actually diamond shaped and and therefore takes 4 strokes to
+//! draw).  If 0 < code < 32, then a useful (but small subset) of
+//! Hershey symbols is plotted.  If 32 <= code <= 127 the
+//! corresponding printable ASCII character is plotted.
+//! @param n : number of points in x and y arrays.
+//! @param x : pointer to an array with X coordinates of points.
+//! @param y : pointer to an array with Y coordinates of points.
+//! @param code : Hershey symbol code (in "ascii-indexed" form with
+//! -1 <= code <= 127) corresponding to a glyph to be plotted at each
+//! of the n points.
 //--------------------------------------------------------------------------
 
 void
@@ -182,9 +203,24 @@
 }
 
 //--------------------------------------------------------------------------
-// void plpoin3(n, x, y, z, code)
-//
-// Draws a series of points in 3 space.  Setup similar to plline3().
+//! Plot a glyph at the specified 3D points.  Setup the call to this
+//! function similar to what is done for plline3.  code=-1 means try
+//! to just draw a point.  Right now it's just a move and a draw at
+//! the same place.  Not ideal, since a sufficiently intelligent
+//! output device may optimize it away, or there may be faster ways of
+//! doing it.  This is OK for now, though, and offers a 4X speedup
+//! over drawing a Hershey font "point" (which is actually diamond
+//! shaped and therefore takes 4 strokes to draw).  If 0 < code < 32,
+//! then a useful (but small subset) of Hershey symbols is plotted.
+//! If 32 <= code <= 127 the corresponding printable ASCII character
+//! is plotted.
+//! @param n : number of points in x, y, and z arrays.
+//! @param x : pointer to an array with X coordinates of points.
+//! @param y : pointer to an array with Y coordinates of points.
+//! @param z : pointer to an array with Z coordinates of points.
+//! @param code : Hershey symbol code (in "ascii-indexed" form with
+//! -1 <= code <= 127) corresponding to a glyph to be plotted at each
+//! of the n points.
 //--------------------------------------------------------------------------
 
 void


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.