From c5e7213469334f369fdaaf10f2f7c8ea99467fec Mon Sep 17 00:00:00 2001
From: gsherman <gsherman@c8812cc2-4d05-0410-92ff-de0c093fc19c>
Date: Sun, 29 Feb 2004 01:55:53 +0000
Subject: [PATCH] Added documentation Refactored accessor functions to get rid
 of the getXXX() signature Added m prefix to private members

git-svn-id: http://svn.osgeo.org/qgis/trunk/qgis@965 c8812cc2-4d05-0410-92ff-de0c093fc19c
---
 src/qgsfield.cpp | 28 +++++++-------
 src/qgsfield.h   | 95 +++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 87 insertions(+), 36 deletions(-)

diff --git a/src/qgsfield.cpp b/src/qgsfield.cpp
index 3fafcbe49e0..7eba4d0208b 100644
--- a/src/qgsfield.cpp
+++ b/src/qgsfield.cpp
@@ -16,50 +16,50 @@
 #include <qstring.h>
 #include "qgsfield.h"
 
-QgsField::QgsField(QString nam, QString typ, int len, int prec):name(nam), type(typ), length(len), precision(prec)
+QgsField::QgsField(QString nam, QString typ, int len, int prec):mName(nam), mType(typ), mLength(len), mPrecision(prec)
 {
   // lower case the field name since some stores use upper case 
   // (eg. shapefiles)
-  name = name.lower();
+  mName = mName.lower();
 }
 
 QgsField::~QgsField()
 {
 }
-QString QgsField::getName()
+QString QgsField::name()
 {
-  return name;
+  return mName;
 }
 
-QString QgsField::getType()
+QString QgsField::type()
 {
-  return type;
+  return mType;
 }
 
-int QgsField::getLength()
+int QgsField::length()
 {
-  return length;
+  return mLength;
 }
 
-int QgsField::getPrecision()
+int QgsField::precision()
 {
-  return precision;
+  return mPrecision;
 }
 
 void QgsField::setName(QString nam)
 {
-  name = nam;
+  mName = nam;
 }
 
 void QgsField::setType(QString typ)
 {
-  type = typ;
+  mType = typ;
 }
 void QgsField::setLength(int len)
 {
-  length = len;
+  mLength = len;
 }
 void QgsField::setPrecision(int prec)
 {
-  precision = prec;
+  mPrecision = prec;
 }
diff --git a/src/qgsfield.h b/src/qgsfield.h
index fc88e4b9616..9b06ca7b8a0 100644
--- a/src/qgsfield.h
+++ b/src/qgsfield.h
@@ -1,9 +1,9 @@
 /***************************************************************************
-    qgsfield.h - Describes a field in a layer or table
-     --------------------------------------
-    Date                 : 01-Jan-2004
-    Copyright            : (C) 2004 by Gary E.Sherman
-    email                : sherman at mrcc.com
+  qgsfield.h - Describes a field in a layer or table
+  --------------------------------------
+Date                 : 01-Jan-2004
+Copyright            : (C) 2004 by Gary E.Sherman
+email                : sherman at mrcc.com
  ***************************************************************************
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -14,23 +14,74 @@
  ***************************************************************************/
 /* $Id$ */
 class QString;
+/**
+  \class QgsField
+  \brief Class to encapsulate a field in an attribute table or data source.
+
+  QgsField stores metadata about an attribute field, including name, type
+  length, and if applicable, precision.
+ */
 
 class QgsField{
-public:
-QgsField(QString nam=0, QString typ=0, int len=0, int prec=0);
-~QgsField();
-QString getName();
-QString getType();
-int getLength();
-int getPrecision();
-
-void setName(QString nam);
-void setType(QString typ);
-void setLength(int len);
-void setPrecision(int prec);
-private:
-QString name;
-QString type;
-int length;
-int precision;
+  public:
+    /** Constructor. Constructs a new QgsField object.
+     * @param nam Field name
+     * @param typ Field type (eg. char, varchar, text, int, serial, double). 
+     Field types are usually unique to the source and are stored exactly
+     as returned from the data store.
+     * @param len Field length
+     * @param prec Field precision. Usually decimal places but may also be
+     * used in conjunction with other fields types (eg. variable character fields)
+     */
+    QgsField(QString nam=0, QString typ=0, int len=0, int prec=0);
+    //! Destructor
+    ~QgsField();
+    //! Gets the name of the field
+    QString name();
+    /** 
+      Gets the field type. Field types vary depending on the data source. Examples
+      are char, int, double, blob, geometry, etc. The type is stored exactly as
+      the data store reports it, with no attenpt to standardize the value.
+      @return QString containing the field type
+     */
+    QString type();
+    /**
+      Gets the length of the field.
+      @return int containing the length of the field
+     */
+    int length();
+    /**
+      Gets the precision of the field. Not all field types have a related precision.
+      @return int containing the precision or zero if not applicable to the field type.
+     */
+    int precision();
+    /**
+      Set the field name.
+      @param nam Name of the field
+     */
+    void setName(QString nam);
+    /**
+      Set the field type.
+      @param typ Field type
+     */
+    void setType(QString typ);
+    /**
+      Set the field length.
+      @param len Length of the field
+     */
+    void setLength(int len);
+    /**
+      Set the field precision.
+      @param prec Precision of the field
+     */
+    void setPrecision(int prec);
+  private:
+    //! Name
+    QString mName;
+    //! Type
+    QString mType;
+    //! Length
+    int mLength;
+    //! Precision
+    int mPrecision;
 };