comment classes A-M with doxygen-compatible comments. Lots of @todo

46 files changed, 132 insertions, 43 deletions

diff --git a/moses/src/AlignmentInfo.h b/moses/src/AlignmentInfo.h
index f3a676558..0278164df 100644
--- a/moses/src/AlignmentInfo.h
+++ b/moses/src/AlignmentInfo.h
@@ -28,7 +28,9 @@ namespace Moses
 
 class AlignmentInfoCollection;
 
-// Collection of non-terminal alignment pairs, ordered by source index.
+/** Collection of non-terminal alignment pairs, ordered by source index.
+  * Usually held by a TargetPhrase to map non-terms in hierarchical/syntax models
+ */
 class AlignmentInfo
 {
   typedef std::set<std::pair<size_t,size_t> > CollType;
@@ -69,8 +71,9 @@ class AlignmentInfo
   NonTermIndexMap m_nonTermIndexMap;
 };
 
-// Define an arbitrary strict weak ordering between AlignmentInfo objects
-// for use by AlignmentInfoCollection.
+/** Define an arbitrary strict weak ordering between AlignmentInfo objects
+ * for use by AlignmentInfoCollection.
+ */
 struct AlignmentInfoOrderer
 {
   bool operator()(const AlignmentInfo &a, const AlignmentInfo &b) const {
diff --git a/moses/src/AlignmentInfoCollection.h b/moses/src/AlignmentInfoCollection.h
index 1a6f4549d..1df90620b 100644
--- a/moses/src/AlignmentInfoCollection.h
+++ b/moses/src/AlignmentInfoCollection.h
@@ -26,7 +26,10 @@
 namespace Moses
 {
 
-// Singleton collection of all AlignmentInfo objects.
+/** Singleton collection of all AlignmentInfo objects.
+ *  Used as a cache of all alignment info to save space.
+ * @todo Check whether this needs locking in threaded environment 
+ */
 class AlignmentInfoCollection
 {
  public:
diff --git a/moses/src/BilingualDynSuffixArray.h b/moses/src/BilingualDynSuffixArray.h
index 137978c14..0198fa12c 100644
--- a/moses/src/BilingualDynSuffixArray.h
+++ b/moses/src/BilingualDynSuffixArray.h
@@ -11,6 +11,8 @@
 
 namespace Moses {
 
+/** @todo ask Abbey Levenberg
+ */
 class SAPhrase
 {
 public:
@@ -29,6 +31,8 @@ public:
   { return words < phr2.words; }
 };
 
+/** @todo ask Abbey Levenberg
+ */
 class PhrasePair
 {
 public:
@@ -45,6 +49,8 @@ public:
 	{ return m_endTarget - m_startTarget + 1; }
 };
 	
+/** @todo ask Abbey Levenberg
+ */
 class SentenceAlignment 
 {
 public:
@@ -77,6 +83,8 @@ private:
   const std::vector<float>& m_weights;
 };
 	
+/** @todo ask Abbey Levenberg
+ */
 class BilingualDynSuffixArray {
 public: 
 	BilingualDynSuffixArray();
diff --git a/moses/src/BitmapContainer.h b/moses/src/BitmapContainer.h
index 987440750..3b9654468 100644
--- a/moses/src/BitmapContainer.h
+++ b/moses/src/BitmapContainer.h
@@ -51,6 +51,7 @@ typedef std::priority_queue< HypothesisQueueItem*, std::vector< HypothesisQueueI
 // Hypothesis Priority Queue Code
 ////////////////////////////////////////////////////////////////////////////////
 
+//! 1 item in the priority queue for stack decoding (phrase-based)
 class HypothesisQueueItem
 {
 private:
@@ -91,7 +92,7 @@ public:
   }
 };
 
-// Allows to compare two HypothesisQueueItem objects by the corresponding scores.
+//! Allows comparison of two HypothesisQueueItem objects by the corresponding scores.
 class QueueItemOrderer
 {
 public:
diff --git a/moses/src/CellCollection.h b/moses/src/CellCollection.h
index 5b99fe0fe..fa724b831 100644
--- a/moses/src/CellCollection.h
+++ b/moses/src/CellCollection.h
@@ -29,6 +29,10 @@ namespace Moses
 {
 class Word;
 
+/** base class of the collection that contains all cells for hierarchical/syntax decoding
+ *  @todo check whether this is still needed. It was required when chart decoding was in 
+ *  a separate lib but that's not the case anymore
+ */
 class CellCollection
 {
 public:
diff --git a/moses/src/ChartCell.h b/moses/src/ChartCell.h
index df332a0f1..ac76e6b50 100644
--- a/moses/src/ChartCell.h
+++ b/moses/src/ChartCell.h
@@ -40,10 +40,12 @@
 namespace Moses
 {
 class ChartTranslationOptionList;
-class ChartTranslationOptionCollection;
 class ChartCellCollection;
 class ChartManager;
 
+/** 1 cell in chart decoder.
+ *  Doesn't directly hold hypotheses. Each cell contain a map of ChartHypothesisCollection that have different LHS non-terms
+ */
 class ChartCell
 {
   friend std::ostream& operator<<(std::ostream&, const ChartCell&);
diff --git a/moses/src/ChartCellCollection.h b/moses/src/ChartCellCollection.h
index 6627b6b67..d618a6703 100644
--- a/moses/src/ChartCellCollection.h
+++ b/moses/src/ChartCellCollection.h
@@ -29,6 +29,8 @@ namespace Moses
 class InputType;
 class ChartManager;
 
+/** Hold all the hypotheses in a chart cell that have the same LHS non-term.
+ */
 class ChartCellCollection : public CellCollection
 {
 public:
diff --git a/moses/src/ChartCellLabel.h b/moses/src/ChartCellLabel.h
index 5228b2af5..2df9a1dec 100644
--- a/moses/src/ChartCellLabel.h
+++ b/moses/src/ChartCellLabel.h
@@ -28,6 +28,11 @@ namespace Moses
 
 class Word;
 
+/** Contains a range, word (terminals?) and a vector of hypotheses.
+ * @todo This is probably incompatible with lattice decoding when the word that spans 
+ *   a position (or positions) can vary.
+ * @todo is this to hold sorted hypotheses that are in the queue for creating the next hypos?
+ */
 class ChartCellLabel
 {
  public:
diff --git a/moses/src/ChartCellLabelSet.h b/moses/src/ChartCellLabelSet.h
index f467f55a5..b828d5fbc 100644
--- a/moses/src/ChartCellLabelSet.h
+++ b/moses/src/ChartCellLabelSet.h
@@ -31,6 +31,8 @@ namespace Moses
 
 class ChartHypothesisCollection;
 
+/** @todo I have no idea what's in here
+ */
 class ChartCellLabelSet
 {
  private:
diff --git a/moses/src/ChartHypothesis.h b/moses/src/ChartHypothesis.h
index edd03df8c..2f525a748 100644
--- a/moses/src/ChartHypothesis.h
+++ b/moses/src/ChartHypothesis.h
@@ -37,6 +37,9 @@ class RuleCubeItem;
 
 typedef std::vector<ChartHypothesis*> ChartArcList;
 
+/** a hypothesis in the hierarchical/syntax decoder.
+ * Contain a pointer to the current target phrase, a vector of previous hypos, and some scores
+ */
 class ChartHypothesis
 {
   friend std::ostream& operator<<(std::ostream&, const ChartHypothesis&);
diff --git a/moses/src/ChartHypothesisCollection.h b/moses/src/ChartHypothesisCollection.h
index ebf1c6002..6c943306a 100644
--- a/moses/src/ChartHypothesisCollection.h
+++ b/moses/src/ChartHypothesisCollection.h
@@ -28,7 +28,7 @@
 namespace Moses
 {
 
-// order by descending score
+//! functor to compare (chart) hypotheses by (descending) score
 class ChartHypothesisScoreOrderer
 {
 public:
@@ -37,6 +37,9 @@ public:
   }
 };
 
+/** functor to compare (chart) hypotheses by feature function states.
+ *  If 2 hypos are equal, according to this functor, then they can be recombined.
+ */
 class ChartHypothesisRecombinationOrderer
 {
 public:
@@ -57,7 +60,9 @@ public:
   }
 };
 
-// 1 of these for each target LHS in each cell
+/** Contains a set of unique hypos that have the same HS non-term.
+  * ie. 1 of these for each target LHS in each cell
+  */
 class ChartHypothesisCollection
 {
   friend std::ostream& operator<<(std::ostream&, const ChartHypothesisCollection&);
diff --git a/moses/src/ChartManager.h b/moses/src/ChartManager.h
index d59975c61..404405641 100644
--- a/moses/src/ChartManager.h
+++ b/moses/src/ChartManager.h
@@ -42,6 +42,8 @@ class ChartTrellisNode;
 class ChartTrellisPath;
 class ChartTrellisPathList;
 
+/** Holds everything you need to decode 1 sentence with the hierachical/syntax decoder
+ */
 class ChartManager
 {
 private:
diff --git a/moses/src/ChartRuleLookupManager.h b/moses/src/ChartRuleLookupManager.h
index 4053a59b1..c502b5fe7 100644
--- a/moses/src/ChartRuleLookupManager.h
+++ b/moses/src/ChartRuleLookupManager.h
@@ -30,11 +30,12 @@ namespace Moses
 class ChartTranslationOptionList;
 class WordsRange;
 
-// Defines an interface for looking up rules in a rule table.  Concrete
-// implementation classes should correspond to specific PhraseDictionary
-// subclasses (memory or on-disk).  Since a ChartRuleLookupManager object
-// maintains sentence-specific state, exactly one should be created for
-// each sentence that is to be decoded.
+/** Defines an interface for looking up rules in a rule table.  Concrete
+ *  implementation classes should correspond to specific PhraseDictionary
+ *  subclasses (memory or on-disk).  Since a ChartRuleLookupManager object
+ *  maintains sentence-specific state, exactly one should be created for
+ *  each sentence that is to be decoded.
+ */
 class ChartRuleLookupManager
 {
 public:
diff --git a/moses/src/ChartTranslationOption.h b/moses/src/ChartTranslationOption.h
index d17f00427..8094c785d 100644
--- a/moses/src/ChartTranslationOption.h
+++ b/moses/src/ChartTranslationOption.h
@@ -30,8 +30,9 @@
 namespace Moses
 {
 
-// Similar to a DottedRule, but contains a direct reference to a list
-// of translations and provdes an estimate of the best score.
+/** Similar to a DottedRule, but contains a direct reference to a list
+ * of translations and provdes an estimate of the best score.
+ */
 class ChartTranslationOption
 {
  public:
diff --git a/moses/src/ChartTranslationOptionCollection.h b/moses/src/ChartTranslationOptionCollection.h
index 4f5b84062..39cdee0c1 100644
--- a/moses/src/ChartTranslationOptionCollection.h
+++ b/moses/src/ChartTranslationOptionCollection.h
@@ -36,6 +36,11 @@ class DottedRule;
 class WordPenaltyProducer;
 class ChartCellCollection;
 
+/** list of list of ALL target phrases for a sentence. NOT translation option
+ * 1 of these is held by the chart manager
+ *  @todo Why is the manager holding target phrases, and not the translation option, or it's collection?
+ *  @todo Why isn't each TargetPhraseCollection held in separate chart cell?
+ */
 class ChartTranslationOptionCollection
 {
 protected:
diff --git a/moses/src/ChartTranslationOptionList.h b/moses/src/ChartTranslationOptionList.h
index 75ef73665..d565b9263 100644
--- a/moses/src/ChartTranslationOptionList.h
+++ b/moses/src/ChartTranslationOptionList.h
@@ -30,7 +30,7 @@ namespace Moses
 class TargetPhraseCollection;
 class WordsRange;
 
-//! a list of target phrases that is trsnalated from the same source phrase
+//! a vector of translations options for a specific range, in a specific sentence
 class ChartTranslationOptionList
 {
  public:
diff --git a/moses/src/ChartTrellisDetour.h b/moses/src/ChartTrellisDetour.h
index a3b07ad00..977ccb67d 100644
--- a/moses/src/ChartTrellisDetour.h
+++ b/moses/src/ChartTrellisDetour.h
@@ -27,6 +27,8 @@ class ChartHypothesis;
 class ChartTrellisNode;
 class ChartTrellisPath;
 
+/** @todo Something to do with make deviant paths
+ */
 class ChartTrellisDetour
 {
  public:
diff --git a/moses/src/ChartTrellisDetourQueue.h b/moses/src/ChartTrellisDetourQueue.h
index f679708e4..d6505d8a2 100644
--- a/moses/src/ChartTrellisDetourQueue.h
+++ b/moses/src/ChartTrellisDetourQueue.h
@@ -25,10 +25,11 @@
 
 namespace Moses {
 
-// A bounded priority queue of ChartTrellisDetour pointers.  The top item is
-// the best scoring detour.  The queue assumes ownership of pushed items and
-// relinquishes ownership when they are popped.  Any remaining items at the
-// time of the queue's destruction are deleted.
+/** A bounded priority queue of ChartTrellisDetour pointers.  The top item is
+ *  the best scoring detour.  The queue assumes ownership of pushed items and
+ *  relinquishes ownership when they are popped.  Any remaining items at the
+ *  time of the queue's destruction are deleted.
+ */
 class ChartTrellisDetourQueue {
  public:
   // Create empty queue with fixed capacity of c.  Capacity 0 means unbounded.
diff --git a/moses/src/ChartTrellisNode.h b/moses/src/ChartTrellisNode.h
index 7b81ff4b2..58203677e 100644
--- a/moses/src/ChartTrellisNode.h
+++ b/moses/src/ChartTrellisNode.h
@@ -30,6 +30,8 @@ class ScoreComponentCollection;
 class ChartHypothesis;
 class ChartTrellisDetour;
 
+/**  1 node in the output hypergraph. Used in ChartTrellisPath
+ */
 class ChartTrellisNode
 {
  public:
diff --git a/moses/src/ChartTrellisPath.h b/moses/src/ChartTrellisPath.h
index 4dee018c3..589fe9158 100644
--- a/moses/src/ChartTrellisPath.h
+++ b/moses/src/ChartTrellisPath.h
@@ -34,6 +34,11 @@ class ChartTrellisDetour;
 class ChartTrellisDetourQueue;
 class ChartTrellisNode;
 
+/** 1 path throught the output hypergraph
+ *  The class hold the final node in the path used for constructing n-best list in chart decoding.
+ *  Each node hold it's own children.
+ *  Also contains the total score and score breakdown for this path.
+ */
 class ChartTrellisPath
 {
  public:
diff --git a/moses/src/ConfusionNet.h b/moses/src/ConfusionNet.h
index 25b5a021d..fdb97a423 100644
--- a/moses/src/ConfusionNet.h
+++ b/moses/src/ConfusionNet.h
@@ -16,6 +16,9 @@ class TranslationOptionCollection;
 class Sentence;
 class TranslationSystem;
 
+/** An input to the decoder where each position can be 1 of a number of words, 
+ *  each with an associated probability. Compared with a sentence, where each position is a word
+ */
 class ConfusionNet : public InputType
 {
 public:
diff --git a/moses/src/DecodeFeature.h b/moses/src/DecodeFeature.h
index 425b8ab75..e65f2d8b9 100644
--- a/moses/src/DecodeFeature.h
+++ b/moses/src/DecodeFeature.h
@@ -33,6 +33,7 @@ namespace Moses
 
 /**
   * A feature on the decoding path (Generation or Translation)
+  * @todo don't quite understand what this is
  **/
 class DecodeFeature : public StatelessFeatureFunction
 {
diff --git a/moses/src/DecodeGraph.h b/moses/src/DecodeGraph.h
index 770cb9958..ad5eb8ace 100644
--- a/moses/src/DecodeGraph.h
+++ b/moses/src/DecodeGraph.h
@@ -33,7 +33,7 @@ namespace Moses
 
 class DecodeStep;
 
-//! list of DecodeStep s which factorizes the translation
+//! list of DecodeSteps which factorizes the translation
 class DecodeGraph
 {
 protected:
diff --git a/moses/src/DecodeStep.h b/moses/src/DecodeStep.h
index 4d2f2280b..26ae84a51 100644
--- a/moses/src/DecodeStep.h
+++ b/moses/src/DecodeStep.h
@@ -39,7 +39,7 @@ class FactorCollection;
 class InputType;
 class TranslationSystem;
 
-/*! Specification for a decoding step.
+/** Specification for a decoding step.
  * The factored translation model consists of Translation and Generation
  * steps, which consult a Dictionary of phrase translations or word
  * generations. This class implements the specification for one of these
diff --git a/moses/src/Dictionary.h b/moses/src/Dictionary.h
index 7bb4d09b1..c6a802ab5 100644
--- a/moses/src/Dictionary.h
+++ b/moses/src/Dictionary.h
@@ -29,9 +29,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 namespace Moses
 {
 
-/** Abstract class from which PhraseDictionary and GenerationDictionary
-	* are inherited.
-*/
+/** Abstract class from which PhraseDictionary and GenerationDictionary are inherited.
+ */
 class Dictionary
 {
 protected:
diff --git a/moses/src/DummyScoreProducers.h b/moses/src/DummyScoreProducers.h
index 399bbf24d..fe0c7fdcf 100644
--- a/moses/src/DummyScoreProducers.h
+++ b/moses/src/DummyScoreProducers.h
@@ -42,7 +42,7 @@ public:
 };
 
 /** Doesn't do anything but provide a key into the global
- * score array to store the word penalty in.
+ *  score array to store the word penalty in.
  */
 class WordPenaltyProducer : public StatelessFeatureFunction
 {
diff --git a/moses/src/DynSuffixArray.h b/moses/src/DynSuffixArray.h
index 05ea0596a..5969195d9 100644
--- a/moses/src/DynSuffixArray.h
+++ b/moses/src/DynSuffixArray.h
@@ -14,6 +14,8 @@ namespace Moses
 
 typedef std::vector<unsigned> vuint_t;
 
+/** @todo ask Abbey Levenberg
+ */
 class DynSuffixArray
 {
 
diff --git a/moses/src/FFState.h b/moses/src/FFState.h
index 209be31b2..527738723 100644
--- a/moses/src/FFState.h
+++ b/moses/src/FFState.h
@@ -8,6 +8,8 @@
 namespace Moses
 {
 
+/** @todo What is the difference between this and the classes in FeatureFunction?
+ */
 class FFState
 {
 public:
diff --git a/moses/src/Factor.h b/moses/src/Factor.h
index 9cf3fd799..ac1b591ed 100644
--- a/moses/src/Factor.h
+++ b/moses/src/Factor.h
@@ -34,7 +34,6 @@ struct FactorFriend;
 class FactorCollection;
 
 /** Represents a factor (word, POS, etc).  
- *
  * A Factor has a contiguous identifier and string value.  
  */
 class Factor
diff --git a/moses/src/FactorCollection.h b/moses/src/FactorCollection.h
index d68d183da..9a01766f4 100644
--- a/moses/src/FactorCollection.h
+++ b/moses/src/FactorCollection.h
@@ -38,7 +38,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 namespace Moses
 {
 
-/* We don't want Factor to be copyable by anybody.  But we also want to store
+/** We don't want Factor to be copyable by anybody.  But we also want to store
  * it in an STL container.  The solution is that Factor's copy constructor is
  * private and friended to FactorFriend.  The STL containers can delegate
  * copying, so friending the container isn't sufficient.  STL containers see
diff --git a/moses/src/FactorTypeSet.h b/moses/src/FactorTypeSet.h
index b0db0502c..5464cee40 100644
--- a/moses/src/FactorTypeSet.h
+++ b/moses/src/FactorTypeSet.h
@@ -32,7 +32,7 @@ namespace Moses
 {
 
 /** set of unique FactorTypes. Used to store what factor types are used in phrase tables etc
-*/
+ */
 class FactorMask : public std::bitset<MAX_NUM_FACTORS>
 {
   friend std::ostream& operator<<(std::ostream&, const FactorMask&);
diff --git a/moses/src/FeatureFunction.h b/moses/src/FeatureFunction.h
index 97d369b09..139725a1a 100644
--- a/moses/src/FeatureFunction.h
+++ b/moses/src/FeatureFunction.h
@@ -15,6 +15,10 @@ class FFState;
 class InputType;
 class ScoreComponentCollection;
 
+/** base class for all feature functions.
+ * @todo is this for pb & hiero too?
+ * @todo what's the diff between FeatureFunction and ScoreProducer?
+ */
 class FeatureFunction: public ScoreProducer
 {
 
@@ -24,6 +28,9 @@ public:
 
 };
 
+/** base class for all stateless feature functions.
+ * eg. phrase table, word penalty, phrase penalty
+ */
 class StatelessFeatureFunction: public FeatureFunction
 {
 
@@ -42,6 +49,9 @@ public:
   bool IsStateless() const;
 };
 
+/** base class for all stateful feature functions.
+ * eg. LM, distortion penalty 
+ */
 class StatefulFeatureFunction: public FeatureFunction
 {
 
diff --git a/moses/src/FilePtr.h b/moses/src/FilePtr.h
index 1613b2f2f..b9c835e59 100644
--- a/moses/src/FilePtr.h
+++ b/moses/src/FilePtr.h
@@ -13,9 +13,9 @@
 namespace Moses
 {
 
-// smart pointer for on-demand loading from file
-// requirement: T has a constructor T(FILE*)
-
+/** smart pointer for on-demand loading from file
+ *  requirement: T has a constructor T(FILE*)
+ */
 template<typename T> class FilePtr
 {
 public:
diff --git a/moses/src/GlobalLexicalModel.h b/moses/src/GlobalLexicalModel.h
index abb5c8f4d..88db637e8 100644
--- a/moses/src/GlobalLexicalModel.h
+++ b/moses/src/GlobalLexicalModel.h
@@ -31,7 +31,6 @@ class InputType;
  * each output word from _all_ the input words. The intuition behind this
  * feature is that it uses context words for disambiguation
  */
-
 class GlobalLexicalModel : public StatelessFeatureFunction
 {
   typedef std::map< const Word*, std::map< const Word*, float, WordComparer >, WordComparer > DoubleHash;
diff --git a/moses/src/HypoList.h b/moses/src/HypoList.h
index 9364399ff..5c3ebe991 100644
--- a/moses/src/HypoList.h
+++ b/moses/src/HypoList.h
@@ -26,6 +26,7 @@ namespace Moses
 
 class ChartHypothesis;
 
+//! vector of chart hypotheses. May get turned into a class
 typedef std::vector<const ChartHypothesis*> HypoList;
 
 }
diff --git a/moses/src/HypothesisStack.h b/moses/src/HypothesisStack.h
index 045773725..26e6ed21b 100644
--- a/moses/src/HypothesisStack.h
+++ b/moses/src/HypothesisStack.h
@@ -11,6 +11,9 @@ namespace Moses
 
 class Manager;
 
+/** abstract unique set of hypotheses that cover a certain number of words, 
+ *  ie. a stack in phrase-based decoding
+ */
 class HypothesisStack
 {
 
diff --git a/moses/src/HypothesisStackCubePruning.h b/moses/src/HypothesisStackCubePruning.h
index 53cad04a1..6dc973ed3 100644
--- a/moses/src/HypothesisStackCubePruning.h
+++ b/moses/src/HypothesisStackCubePruning.h
@@ -38,7 +38,7 @@ class Manager;
 
 typedef std::map<WordsBitmap, BitmapContainer*> _BMType;
 
-/** Stack for instances of Hypothesis, includes functions for pruning. */
+/** A stack for phrase-based decoding with cube-pruning. */
 class HypothesisStackCubePruning : public HypothesisStack
 {
 public:
diff --git a/moses/src/HypothesisStackNormal.h b/moses/src/HypothesisStackNormal.h
index d991ec373..5be07f20e 100644
--- a/moses/src/HypothesisStackNormal.h
+++ b/moses/src/HypothesisStackNormal.h
@@ -33,7 +33,7 @@ namespace Moses
 // class WordsBitmap;
 // typedef size_t WordsBitmapID;
 
-/** Stack for instances of Hypothesis, includes functions for pruning. */
+/** A stack for standard phrase-based decoding. */
 class HypothesisStackNormal: public HypothesisStack
 {
 public:
diff --git a/moses/src/InputType.h b/moses/src/InputType.h
index 8a29ca279..982641e51 100644
--- a/moses/src/InputType.h
+++ b/moses/src/InputType.h
@@ -40,7 +40,9 @@ class TranslationOptionCollection;
 class TranslationSystem;
 class ChartTranslationOption;
   
-//! base class for sentences and confusion networks
+/** base class for all types of inputs to the decoder,
+ *  eg. sentences, confusion networks, lattices and tree 
+ */
 class InputType
 {
 protected:
diff --git a/moses/src/LMList.h b/moses/src/LMList.h
index 5b58b7cc0..c808828b1 100644
--- a/moses/src/LMList.h
+++ b/moses/src/LMList.h
@@ -11,7 +11,7 @@ class Phrase;
 class ScoreColl;
 class ScoreComponentCollection;
 
-//! List of language models
+//! List of language models and function to calc scores from each LM, given a phrase
 class LMList
 {
 protected:
diff --git a/moses/src/LVoc.h b/moses/src/LVoc.h
index ec20fe3cd..485e3f481 100644
--- a/moses/src/LVoc.h
+++ b/moses/src/LVoc.h
@@ -13,8 +13,11 @@ extern const LabelId Epsilon;
 
 typedef std::vector<LabelId> IPhrase;
 
-// A = type of things to numberize, ie, std::string
-// B = map type to use, might consider using hash_map for better performance
+/** class used in phrase-based binary phrase-table.
+ *  @todo vocab?
+ *  A = type of things to numberize, ie, std::string
+ *  B = map type to use, might consider using hash_map for better performance
+ */
 template<typename A,typename B=std::map<A,LabelId> >
 class LVoc
 {
diff --git a/moses/src/LexicalReordering.h b/moses/src/LexicalReordering.h
index d7be460f8..13786a17a 100644
--- a/moses/src/LexicalReordering.h
+++ b/moses/src/LexicalReordering.h
@@ -22,6 +22,8 @@ class Phrase;
 class Hypothesis;
 class InputType;
 
+/** implementation of lexical reordering (Tilman ...) for phrase-based decoding
+ */
 class LexicalReordering : public StatefulFeatureFunction
 {
 public:
diff --git a/moses/src/LexicalReorderingState.h b/moses/src/LexicalReorderingState.h
index 877dc5f35..111f57da5 100644
--- a/moses/src/LexicalReorderingState.h
+++ b/moses/src/LexicalReorderingState.h
@@ -17,7 +17,9 @@ namespace Moses
 {
 class LexicalReorderingState;
 
-//! Factory class for lexical reordering states
+/** Factory class for lexical reordering states
+ *  @todo There's a lot of classes for lexicalized reordering. Perhaps put them in a separate dir
+ */
 class LexicalReorderingConfiguration
 {
 public:
@@ -108,6 +110,7 @@ protected:
   static const ReorderingType L = 1;  // left
 };
 
+//! @todo what is this?
 class BidirectionalReorderingState : public LexicalReorderingState
 {
 private:
diff --git a/moses/src/LexicalReorderingTable.h b/moses/src/LexicalReorderingTable.h
index ae10ae386..abd8e9ac9 100644
--- a/moses/src/LexicalReorderingTable.h
+++ b/moses/src/LexicalReorderingTable.h
@@ -27,8 +27,7 @@ class Phrase;
 class InputType;
 class ConfusionNet;
 
-//additional types
-
+//! additional types
 class LexicalReorderingTable
 {
 public:
@@ -69,6 +68,7 @@ protected:
   FactorList m_FactorsC;
 };
 
+//! @todo what is this?
 class LexicalReorderingTableMemory : public LexicalReorderingTable
 {
   //implements LexicalReorderingTable saving all scores in one large std::map<> thingy
diff --git a/moses/src/Manager.h b/moses/src/Manager.h
index 3946e54d7..ea22be568 100644
--- a/moses/src/Manager.h
+++ b/moses/src/Manager.h
@@ -59,7 +59,7 @@ struct SearchGraphNode {
 
 };
 
-/** The Manager class implements a stack decoding algorithm.
+/** The Manager class implements a stack decoding algorithm for phrase-based decoding
  * Hypotheses are organized in stacks. One stack contains all hypothesis that have
  * the same number of foreign words translated.  The data structure for hypothesis
  * stacks is the class HypothesisStack. The data structure for a hypothesis
diff --git a/moses/src/gzfilebuf.h b/moses/src/gzfilebuf.h
index d59d3e1b7..2376c2875 100644
--- a/moses/src/gzfilebuf.h
+++ b/moses/src/gzfilebuf.h
@@ -5,6 +5,9 @@
 #include <zlib.h>
 #include <cstring>
 
+/** wrapper around gzip input stream. Unknown parentage
+ *  @todo replace with boost version - output stream already uses it
+ */
 class gzfilebuf : public std::streambuf
 {
 public: