From, Leandro Motta Barros, Doxygen comments.

Ammendments by Robert Osfield, a few comment rewrites to better reflect API functionality/usage.

include/osg/Drawable

@@ -364,12 +364,11 @@ class SG_EXPORT Drawable : public Object
 
 
 
-        /** Draw the \c Geometry "directly", that is, by issuing all the OpenGL
+        /** drawImplementation(State&) is a pure virtaul method for the actual implementation of OpenGL drawing calls, such as vertex arrays and primitives, that
-          * calls needed to draw it. Contrast this with \c draw(), that can
+          * must be implemented in concrete subclasses of the Drawable base class, examples include osg::Geometry and osg::ShapeDrawable.
-          * compile and use an OpenGL display list to do the rendering.
+          * drawImplementation(State&) is called from the draw(State&) method, with the draw method handling management of OpenGL display lists,
-          * <p> This is the internal draw method which does the drawing itself,
+          * and drawImplementation(State&) handling the actuall drawing itself.  
-          * and is the method to override when deriving from \c Drawable.
+          * @param state The osg::State object that encapulates the current OpenGL state for the current graphics context. */
-          */
         virtual void drawImplementation(State& state) const = 0;
 
 

include/osg/State

@@ -60,8 +60,20 @@ namespace osg {
         }\
     }
 
-/** State class for managing a state stack.
+/** Encapsulates the current applied OpenGL modes, attributes and vertex arrays settings,.
-  * Lazy state updating is used to minimize state changes.
+  * implements lazy state updating and provides accessors for querrying the current state.
+  . The venerable Red Book says that "OpenGL is a state machine", and this class
+  * represents the OpenGL state in OSG. Furthermore, \c State also has other
+  * important features:
+  * - It works as a stack of states (see \c pushStateSet() and
+  *   \c popStateSet()). Manipulating this stack of OpenGL states manually is
+  *   seldom needed, since OSG does this is the most common situations.
+  * - It implements lazy state updating. This means that, if one requests a
+  *   state change and that particular state is already in the requested stated, no OpenGL
+  *   call will be made, this ensures that OpenGL pipeline is not stalled by unncessary state changes.
+  * - It allows to query the current OpenGL state without calls to \c glGet*(),
+  *   which typically stall the graphics pipeline (see, for instance,
+  *   \c captureCurrentState() and \c getModelViewMatrix()).
   */
 class SG_EXPORT State : public Referenced
 {
@@ -149,7 +161,10 @@ class SG_EXPORT State : public Referenced
         /** Apply stateset.*/
         void apply(const StateSet* dstate);
 
-        /** Apply the state.*/
+        /** Updates the OpenGL state so that it matches the \c StateSet at the
+          * top of the stack of <tt>StateSet</tt>s maintained internally by a
+          * \c State.
+         */
         void apply();
 
 
@@ -165,7 +180,15 @@ class SG_EXPORT State : public Referenced
         }
 
 
-        /** Apply an OpenGL mode if required. */
+        /** Apply an OpenGL mode if required. This is a wrapper around
+          * \c glEnable() and \c glDisable(), that just actually calls these
+          * functions if the \c enabled flag is different than the current
+          * state.
+          * @return \c true if the state was actually changed. \c false
+          *         otherwise. Notice that a \c false return does not indicate
+          *         an error, it just means that the mode was already set to the
+          *         same value as the \c enabled parameter.
+        */
         inline bool applyMode(StateAttribute::GLMode mode,bool enabled)
         {
             ModeStack& ms = _modeMap[mode];
@@ -734,7 +757,15 @@ class SG_EXPORT State : public Referenced
         };
 
 
-        /** apply an OpenGL mode if required, passing in mode, enable flag and appropriate mode stack */
+        /** Apply an OpenGL mode if required, passing in mode, enable flag and
+          * appropriate mode stack. This is a wrapper around \c glEnable() and
+          * \c glDisable(), that just actually calls these functions if the
+          * \c enabled flag is different than the current state.
+          * @return \c true if the state was actually changed. \c false
+          *         otherwise. Notice that a \c false return does not indicate
+          *         an error, it just means that the mode was already set to the
+          *         same value as the \c enabled parameter.
+        */
         inline bool applyMode(StateAttribute::GLMode mode,bool enabled,ModeStack& ms)
         {
             if (ms.last_applied_value != enabled)

include/osg/StateSet

@@ -29,12 +29,14 @@
 
 namespace osg {
 
-/**
+/** Stores a set of modes and attributes which respresent a set of OpenGL state.
-Encapsulates OpenGL state modes and attributes. 
+  *  Notice that a \c StateSet contains just a subset of the whole OpenGL state.
-Used to specific textures etc of osg::Drawable's which hold references
+  * <p>In OSG, each \c Drawable and each \c Node has a reference to a
-to a single osg::StateSet.  StateSet can be shared between Drawable's
+  * \c StateSet. These <tt>StateSet</tt>s can be shared between
-and is recommend if possible as it minimizes expensive state changes
+  * different <tt>Drawable</tt>s and <tt>Node</tt>s (that is, several
-in the graphics pipeline.
+  * <tt>Drawable</tt>s and <tt>Node</tt>s can reference the same \c StateSet).
+  * Indeed, this practice is recommended whenever possible,
+  * as this minimizes expensive state changes in the graphics pipeline.
 */
 class SG_EXPORT StateSet : public Object
 {
@@ -70,14 +72,22 @@ class SG_EXPORT StateSet : public Object
         /** Clear the StateSet of all modes and attributes.*/
         void clear();
 
-        /** merge this stateset with stateset rhs, this overrides
+        /** Merge this \c StateSet with the \c StateSet passed as parameter.
-          * the rhs if OVERRIDE is specified, otherwise rhs takes precedence.*/
+          * Every mode and attribute in this \c StateSet that is marked with
+          * \c StateAttribute::OVERRIDE is replaced with the
+          * equivalent mode or attribute from \c rhs.
+        */
         void merge(const StateSet& rhs);
 
         /** a container to map GLModes to their respective GLModeValues.*/
         typedef std::map<StateAttribute::GLMode,StateAttribute::GLModeValue>  ModeList;
 
-        /** Set this StateSet to contain specified GLMode and value.*/
+        /** Set this \c StateSet to contain the specified \c GLMode with a given
+          * value.
+          * @note Don't use this method to set modes related to textures. For this
+          *       purpose, use \c setTextureMode(), that accepts an extra parameter
+          *       specifying which texture unit shall be affected by the call.
+        */
         void setMode(StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
 
 #ifdef USE_DEPRECATED_API
@@ -85,20 +95,35 @@ class SG_EXPORT StateSet : public Object
           * Has the effect of deleting any GLMode of specified type from StateSet.*/
         void setModeToInherit(StateAttribute::GLMode mode) { removeMode(mode); }
 #endif
-        /** Remove mode from StateSet.*/
+        /** Remove \c mode from this \c StateSet.
+          * @note Don't use this method to remove modes related to textures. For
+          *       this purpose, use \c removeTextureMode(), that accepts an extra
+          *       parameter specifying which texture unit shall be affected by
+          *       the call.
+        */
         void removeMode(StateAttribute::GLMode mode);
 
-        /** Get specified GLModeValue for specified GLMode.
+        /** Get the value for a given \c GLMode.
-          * returns INHERIT if no GLModeValue is contained within StateSet.*/
+          * @param mode The \c GLMode whose value is desired.
+          * @return If \c mode is contained within this \c StateSet, returns the
+          *         value associated with it. Otherwise, returns
+          *         \c StateAttribute::INHERIT.
+          * @note Don't use this method to get the value of modes related to
+          *       textures. For this purpose, use \c removeTextureMode(), that
+          *       accepts an extra parameter specifying which texture unit shall
+          *       be affected by the call.
+        */
         StateAttribute::GLModeValue getMode(StateAttribute::GLMode mode) const;
 
-        /** set the list of all GLModes contained in this StateSet.*/
+        /** Set the list of all <tt>GLMode</tt>s contained in this \c StateSet.*/
         inline void setModeList(ModeList& ml) { _modeList=ml; }
 
-        /** return the list of all GLModes contained in this StateSet.*/
+        /** Return the list of all <tt>GLMode</tt>s contained in this \c StateSet.*/
         inline ModeList& getModeList() { return _modeList; }
 
-        /** return the const list of all GLModes contained in this const StateSet.*/
+        /** Return the \c const list of all <tt>GLMode</tt>s contained in this
+          * <tt>const StateSet</tt>.
+        */
         inline const ModeList& getModeList() const { return _modeList; }
 
 
@@ -151,7 +176,13 @@ class SG_EXPORT StateSet : public Object
 
         typedef std::vector<ModeList>       TextureModeList;
 
-        /** Set this StateSet to contain specified GLMode and value.*/
+        /** Set this \c StateSet to contain specified \c GLMode with a given
+         *  value.
+         *  @param unit The texture unit to be affected (used with
+         *         multi-texturing).
+         *  @param mode The OpenGL mode to be added to the \c StateSet.
+         *  @param value The value to be assigned to \c mode.
+        */
         void setTextureMode(unsigned int unit,StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
 
 #ifdef USE_DEPRECATED_API
@@ -228,14 +259,20 @@ class SG_EXPORT StateSet : public Object
             TRANSPARENT_BIN = 2
         };
 
-        /** Set the RenderingHint of the StateSet.
+        /** Set the \c RenderingHint of this \c StateSet. \c RenderingHint is
-          * RenderingHint is used by osgUtil::Renderer to determine which
+          * used by the renderer to determine which draw bin to drop associated
-          * draw bin to drop associated osg::Drawables in. For opaque
+          * <tt>osg::Drawable</tt>s in. Typically, users will set this to either
-          * objects OPAQUE_BIN would typical used, which TRANSPARENT_BIN
+          * \c StateSet::OPAQUE_BIN or \c StateSet::TRANSPARENT_BIN.
-          * should be used for objects which need to be depth sorted.*/
+          * <tt>Drawable</tt>s in the opaque bin are sorted by their
+          * \c StateSet, so that the number of expensive changes in the OpenGL
+          * state is minimized. <tt>Drawable</tt>s in the transparent bin are
+          * sorted by depth, so that objects farther from the viewer are
+          * rendered first (and hence alpha blending works nicely for
+          * translucent objects).
+        */
         void setRenderingHint(int hint);
 
-        /** Get the RenderingHint of the StateSet.*/
+        /** Get the \c RenderingHint of this \c StateSet.*/
         inline int getRenderingHint() const      { return _renderingHint; }
 
         enum RenderBinMode