Index: kernel/include/IMP/ScoreState.h
===================================================================
--- kernel/include/IMP/ScoreState.h	(revision 441)
+++ kernel/include/IMP/ScoreState.h	(working copy)
@@ -24,6 +24,14 @@
 class Model;
 
 //! Shared score state.
+/** ScoreStates should be used to generate state that needs to be
+    updated every time Particle attributes change. 
+
+    ScoreStates can change the state of particles and restraints.
+    However, optimizers may not  pick up new particles or changes
+    to whether particular attributes are optimized or not.
+
+ */
 class IMPDLLEXPORT ScoreState : public internal::Object
 {
   friend class Model;
@@ -36,6 +44,9 @@
   // Update the state given the current state of the model
   virtual void update() = 0;
 
+  //! Show the ScoreState
+  /** The output of show may take several lines and should end in a newline.
+   */
   virtual void show(std::ostream& out = std::cout) const;
 
   //! \return version and authorship information.
Index: kernel/include/IMP/Restraint.h
===================================================================
--- kernel/include/IMP/Restraint.h	(revision 441)
+++ kernel/include/IMP/Restraint.h	(working copy)
@@ -61,6 +61,7 @@
 
   //! Show the current restraint.
   /** \param[in] out Stream to send restraint description to.
+      The output of show may take several lines and should end in a newline.
    */
   virtual void show(std::ostream& out=std::cout) const;