Changeset 5bf941 for molecuilder

Timestamp:

Feb 24, 2010, 4:44:58 PM (16 years ago)

Author:

Tillmann Crueger <crueger@…>

Children:

e7e088

Parents:

7bfc19

Message:

Improved documentation of the World-class

File:

• molecuilder/src/World.hpp (modified) (3 diffs)

molecuilder/src/World.hpp

@@ -46 +46 @@
   /***** getter and setter *****/
   // reference to pointer is used for legacy reason... reference will be removed latter to keep encapsulation of World object
+  /**
+   * returns the periodentafel for the world.
+   */
   periodentafel *&getPeriode();
+
+  /**
+   * returns the first atom that matches a given descriptor.
+   * Do not rely on ordering for descriptors that match more than one atom.
+   */
   atom* getAtom(AtomDescriptor descriptor);
+
+  /**
+   * returns a vector containing all atoms that match a given descriptor
+   */
   std::vector<atom*> getAllAtoms(AtomDescriptor descriptor);
 
+  /**
+   * returns a calculation that calls a given function on all atoms matching a descriptor.
+   * the calculation is not called at this point and can be used as an action, i.e. be stored in
+   * menus, be kept around for later use etc.
+   */
   template<typename T>
   AtomsCalculation<T>* calcOnAtoms(boost::function<T(atom*)>,std::string,AtomDescriptor);
 
+  /**
+   * get the number of atoms in the World
+   */
   int numAtoms();
+
+  /**
+   * get the number of molecules in the World
+   */
   int numMolecules();
 
   /***** Methods to work with the World *****/
+
+  /**
+   * create a new molecule. This method should be used whenever any kind of molecule is needed. Assigns a unique
+   * ID to the molecule and stores it in the World for later retrieval. Do not create molecules directly.
+   */
   molecule *createMolecule();
+
+  /**
+   * Create a new atom. This method should be used whenever any atom is needed. Assigns a unique ID and stores
+   * the atom in the World. If the atom is not destroyed it will automatically be destroyed when the world ends.
+   */
   atom *createAtom();
+
+  /**
+   * Registers a Atom unknown to world. Needed in some rare cases, e.g. when cloning atoms, or in some unittests.
+   * Do not re-register Atoms already known to the world since this will cause double-frees.
+   */
   int registerAtom(atom*);
+
+  /**
+     * Delete some atom and erase it from the world. Use this whenever you need to destroy any atom. Do not call delete on
+     * atom directly since this will leave the pointer inside the world.
+   */
   void destroyAtom(atom*);
+
+  /**
+   * Delete some atom and erase it from the world. Use this whenever you need to destroy any atom. Do not call delete on
+   * atom directly since this will leave the pointer inside the world.
+   */
   void destroyAtom(int);
 
+  /**
+   * Produces a process that calls a function on all Atoms matching a given descriptor. The process is not
+   * called at this time, so it can be passed around, stored inside menuItems etc.
+   */
   ManipulateAtomsProcess* manipulateAtoms(boost::function<void(atom*)>,std::string,AtomDescriptor);
 
@@ -90 +143 @@
   };
 
+  /**
+   * returns an iterator over all Atoms matching a given descriptor.
+   * used for internal purposes, like AtomProcesses and AtomCalculations.
+   */
   AtomIterator getAtomIter(AtomDescriptor descr);
+
+  /**
+   * returns an iterator to the end of the AtomList. Due to overloading this iterator
+   * can be compared to iterators produced by getAtomIter (see the mis-matching types).
+   * Thus it can be used to detect when such an iterator is at the end of the list.
+   * used for internal purposes, like AtomProcesses and AtomCalculations.
+   */
   AtomList::iterator atomEnd();
 
@@ -105 +169 @@
   /***** singleton Stuff *****/
 public:
+
+  /**
+   * get the currently active instance of the World.
+   */
   static World* get();
+
+  /**
+   * destroy the currently active instance of the World.
+   */
   static void destroy();
+
+  /**
+   * destroy the currently active instance of the World and immidiately
+   * create a new one. Use this to reset while somebody is still Observing
+   * the world and should reset the observed instance. All observers will be
+   * sent the subjectKille() message from the old world.
+   */
   static World* reset();
 
 private:
+  /**
+   * private constructor to ensure creation of the world using
+   * the singleton pattern.
+   */
   World();
+
+  /**
+   * private destructor to ensure destruction of the world using the
+   * singleton pattern.
+   */
   virtual ~World();