Index: /cpp/frams/model/model.h
===================================================================
--- /cpp/frams/model/model.h	(revision 303)
+++ /cpp/frams/model/model.h	(revision 304)
@@ -223,8 +223,9 @@
 void makeGeno(Geno &,MultiMap *map=0,bool handle_defaults=true);
 
-/** @return mapping from source genotype (0-based position in text) to model elements reference numbers.
-    the map can be empty if the mapping hasn't been requested earlier (in constructor)
+/** @return Mapping from source genotype (0-based position in text) to model elements reference numbers.
+    Read about how mappings work: http://www.framsticks.com/files/common/GeneticMappingsInArtificialGenomes.pdf
+    The map can be empty if the mapping hasn't been requested earlier (in constructor)
     or the converters don't support mapping.
-    if you create or modify the model using singleStepBuild() or direct manipulation
+    If you create or modify the model using singleStepBuild() or direct manipulation
     the map will be not changed or created automatically - it is your responsibility.
     @see Model(const Geno &src,int buildmaps=0), singleStepBuild(), PartBase::addMapping()
@@ -235,5 +236,6 @@
 MultiMap &getMap();
 
-/** @return mapping from f0 genotype (0-based position in text) to model elements reference numbers
+/** Read about how mappings work: http://www.framsticks.com/files/common/GeneticMappingsInArtificialGenomes.pdf
+    @return mapping from f0 genotype (0-based position in text) to model elements reference numbers
  */
 const MultiMap &getF0Map();
@@ -246,6 +248,7 @@
 void clearMap();
 
-/** generate mapping from the current genotype to the f0 genotype.
+/** Generate mapping from the current genotype to the f0 genotype.
     This works only if both current and f0 maps are already known.
+    Read about how mappings work: http://www.framsticks.com/files/common/GeneticMappingsInArtificialGenomes.pdf
     @see convmap
 */
@@ -268,6 +271,6 @@
 void clear();
 
-/** execute single line of <B>f0</B> genotype.
-    return value is non-negative reference number of the created item,
+/** Execute single line of <B>f0</B> genotype.
+    Return value is non-negative reference number of the created item,
     or negative value. reference number can be used to access
     the item using getPart(int), getJoint(int) and getNeuroItem(int) methods.
@@ -285,18 +288,18 @@
 void useAllDelta(bool yesno);
 
-/// final validity check of the model, all model data has to be available at this point.
-/// if the model was modified, the genotype will be also updated.
-/// it also calls "validate" with all side effects.
+/// Final validity check of the model, all model data has to be available at this point.
+/// If the model was modified, the genotype will be also updated.
+/// It also calls "validate" with all side effects.
 /// @return > 0 means "valid"
 int close();
 
-/// enable model building.
-/// you should use it if you need to create new model, modify the model after close
+/// Enable model building.
+/// You should use it if you need to create new model, modify the model after close
 /// or modify the model created from the genotype.
-/// between open() and close() the model is not fully usable, 
+/// Between open() and close() the model is not fully usable.
 void open();
 
-/// current model written as f0 genotype while building
-/// (not cached, not validated, probably unusable and bad if used before close(). but good for debugging.)
+/// Current model written as f0 genotype while building
+/// (not cached, not validated, probably unusable and bad if used before close(). But good for debugging.)
 Geno rawGeno();
 
Index: /cpp/frams/util/multimap.h
===================================================================
--- /cpp/frams/util/multimap.h	(revision 303)
+++ /cpp/frams/util/multimap.h	(revision 304)
@@ -19,6 +19,7 @@
 
 /** MultiMap - used for conversion mapping.
+    Read about how mappings work: http://www.framsticks.com/files/common/GeneticMappingsInArtificialGenomes.pdf
     see @ref convmap
-  */
+*/
 class MultiMap
 {
@@ -73,4 +74,2 @@
 
 #endif
-
-
