Changeset 02ee15 for src/World.hpp

Timestamp:

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

Author:

Tillmann Crueger <crueger@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

f16a4b

Parents:

46d958

Message:

Improved documentation of the World-class

File:

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

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();