Context Navigation

-              ra1510d
+              rdbb474
 #include "Actions/Process.hpp"
+/**
+ * A calculation is a Process that has some kind of result.
+ *
+ * This class can be used in the same way as any other Action or Process, but has some special methods
+ * for inspecting the result of the calculation.
+ */
 template<typename T>
 class Calculation : public Process
 …
   virtual ~Calculation();
+  /**
+   * Reimplemented call method for Action Base class.
+   * Resets the result and then redoes the calculation. Can be used to retrigger calculations
+   * from menu Items or other places.
+   */
   virtual void call();
   virtual void undo();
   virtual bool canUndo();
+  /**
+   * Does the actual calculation and returns the result.
+   * When the calculation has been done before it is not redone, but the previous cached result is returned.
+   * Call reset to delete the cached value.
+   */
   virtual T operator()();
+  /**
+   * Check if a cached result is available.
+   */
   virtual bool hasResult();
+  /**
+   * Get the cached result.
+   * Fails if there is no cached result.
+   */
   virtual T getResult();
+  /**
+   * Delete a previously calculated result from the cache.
+   */
   virtual void reset();
 protected:
   T* result;
+  /**
+   * Pure virtual method for implementation of the actual calculation procedure.
+   */
   virtual T* doCalc()=0;
 private:

src/Actions/Process.cpp

ra1510d	rdbb474
73	73	{
74	74	OBSERVE;
75		~~active = true;~~
76	75	currStep=0;
77	76	}
78	77	starts = false;
	78	active = true;
79	79	}
80	80
…	…
85	85
86	86	void Process::stop(){
	87	active=false;
87	88	stops = true;
88	89	{
89	90	OBSERVE;
90	91	currStep=0;
91		~~active=false;~~
92	92	}
93	93	{

src/Actions/Process.hpp

-              ra1510d
+              rdbb474
 #include "Actions/Action.hpp"
+/**
+ * A Process is an Action that might take some time and therefore has special
+ * methods to allow communication with progress indicators. Indicators
+ * can sign on at a global place and will be notified when any process is doing
+ * a calculation.
+ *
+ * A Process has four states:
+ *  - starting: It is in the process of setting itself up, and wants everybody to know that it will start
+ *              the calculation soon. Indicators should set up anything they need for displaying the progress
+ *              when they are notified by a process in this state.
+ *  - active:   The process is currently doing it's thing and wants any indicator to know it's status, i.e.
+ *              the percentage done.
+ *  - stopping: The process has fullfilled it's purpose and is shutting down. Indicators recieving this status
+ *              should also use it to shut down their indication mechanism and delete any objects allocated for
+ *              this Process
+ *  - inactive: This Process is currently sleeping. If a Process is sending out any signals in this state, there
+ *              is something seriously wrong.
+ */
 class Process : public Action, public Observable
+{

src/Descriptors/AtomDescriptor.hpp

-              ra1510d
+              rdbb474
 class AtomDescripter_impl;
+/**
+ * An AtomDescriptor describes a Set of Atoms from the World. Can be used for any method that needs to work on
+ * a specific set of Atoms.
+ *
+ * This Class is implemented using the PIMPL-Idion, i.e. this class only contains an abstract structure
+ * that forwards any request to a wrapped pointer-to-implementation. This way operators and calculations
+ * on Descriptors are possible.
+ *
+ * Concrete Implementation Objects can be shared between multiple Wrappers, so make sure that
+ * any Implementation remainst constant during lifetime.
+ */
 class AtomDescriptor {
   // close coupling to the world to allow access
 …
 public:
   typedef boost::shared_ptr<AtomDescriptor_impl> impl_ptr;
+  typedef boost::shared_ptr<AtomDescriptor_impl> impl_ptr; //!< Allow easy changes of the pointer-to-implementation type
   AtomDescriptor(impl_ptr);
+  /**
+   * Copy constructor.
+   * Takes the Implementation from the copied object and sets it's own pointer to link there.
+   * This way the actuall implementation object is shared between copy and original
+   */
   AtomDescriptor(const AtomDescriptor&);
   ~AtomDescriptor();
+  /**
+   * Assignment Operator.
+   *
+   * Implemented by setting the pointer to the new Implementation.
+   */
   AtomDescriptor &operator=(AtomDescriptor &);
 protected:
+  /**
+   * forward Method to implementation
+   */
   atom* find();
+  /**
+   * forward Method to implementation
+   */
   std::vector<atom*> findAll();
+  /**
+   * Return the implementation this Wrapper currently points to.
+   * Used for copying, assignment and in Iterators over subsets of the World.
+   */
   impl_ptr get_impl() const;
 …
 };
+// Functions to construct actual descriptors
+/**
+ * produce an Atomdescriptor that at the point of construction contains an implementation that matches all Atoms
+ */
 AtomDescriptor AllAtoms();
+/**
+ * produce an Atomdescriptor that at the point of construction contains an implementation that matches no Atoms
+ */
 AtomDescriptor NoAtoms();
+// no true short circuit, but the test of the second descriptor wont be done
+/**
+ * Set Intersection for two Atomdescriptors. The resulting Atomdescriptor will only match an Atom if both
+ * given Atomdescriptors also match. Uses short circuit inside, so the second predicate wont be called
+ * when the first one failed.
+ */
 AtomDescriptor operator&&(const AtomDescriptor &lhs, const AtomDescriptor &rhs);
+/**
+ * Set Union for two AtomDescriptors. The resulting AtomDescriptor will match an Atom if at least one of
+ * the two given AtomDescriptors does match. Used short circuit inside, so the second predicate wont
+ * be called when the first one failed.
+ */
 AtomDescriptor operator||(const AtomDescriptor &lhs, const AtomDescriptor &rhs);
+/**
+ * Set inversion for an AtomDescriptor. Matches an Atom if the given AtomDescriptor did not match.
+ */
 AtomDescriptor operator!(const AtomDescriptor &arg);

src/Descriptors/AtomDescriptor_impl.hpp

-              ra1510d
+              rdbb474
 /************************ Declarations of implementation Objects ************************/
+/**
+ * This class implements a general Base class for AtomDescriptors using the PIMPL-Idiom
+ *
+ * The predicate for this class is empty and should be implemented by derived classes.
+ * By the predicate it is described which atoms should be picked for a given descriptor.
+ */
 class AtomDescriptor_impl
 …
   virtual ~AtomDescriptor_impl();
+  /**
+   * Implement this abstract Method to make a concrete AtomDescriptor pick certain Atoms
+   */
   virtual bool predicate(std::pair<atomId_t,atom*>)=0;
 protected:
+  /**
+   * This method is called when the Descriptor is used to find the first matching
+   * Atom. Walks through all Atoms and stops on the first match. Can be implemented
+   * when the searched Atom can be found in a more efficient way. Calculated
+   * Atomdescriptors will always use this method, so no improvement there.
+   */
   virtual atom* find();
+  /**
+   * This method is called when the Descriptor is used to find all matching Atoms.
+   * Walks through all Atoms and tests the predicate on each one. A vector of all
+   * matching Atoms is returned.
+   */
   virtual std::vector<atom*> findAll();
+  /**
+   * This method is used internally to query the Set of Atoms from the world.
+   * By using this method derived classes can also access the Internal World Datastructre.
+   * Implemented in full in the Base Descriptor Implementation, so only this one method
+   * needs to be friend with the World class.
+   */
   World::AtomSet& getAtoms();
 };
 …
 /************************** Universe and Emptyset *****************/
+/**
+ * A simple AtomDescriptor that will always match all Atoms present in the World.
+ */
 class AtomAllDescriptor_impl : public AtomDescriptor_impl {
 public:
   AtomAllDescriptor_impl();
   virtual ~AtomAllDescriptor_impl();
+  /**
+   * Always returns true for any Atom
+   */
   virtual bool predicate(std::pair<atomId_t,atom*>);
 };
+/**
+ * An AtomDescriptor that never matches any Atom in the World.
+ */
 class AtomNoneDescriptor_impl : public AtomDescriptor_impl {
 public:
   AtomNoneDescriptor_impl();
   virtual ~AtomNoneDescriptor_impl();
+  /**
+   * Always returns false for any Atom
+   */
   virtual bool predicate(std::pair<atomId_t,atom*>);
 };
 …
 /************************** Operator stuff ************************/
+/**
+ * Intersection of two AtomDescriptors
+ */
 class AtomAndDescriptor_impl : public AtomDescriptor_impl
+{
 …
   AtomAndDescriptor_impl(AtomDescriptor::impl_ptr _lhs, AtomDescriptor::impl_ptr _rhs);
   ~AtomAndDescriptor_impl();
+  /**
+   * This predicate uses the predicate from the first && the predicate from the
+   * second Descriptor to decide if an Atom should be selected.
+   */
   virtual bool predicate(std::pair<atomId_t,atom*>);
 …
 };
+/**
+ * Union of two AtomDescriptors
+ */
 class AtomOrDescriptor_impl : public AtomDescriptor_impl
+{
 …
   AtomOrDescriptor_impl(AtomDescriptor::impl_ptr _lhs, AtomDescriptor::impl_ptr _rhs);
   virtual ~AtomOrDescriptor_impl();
+  /**
+   * This predicate uses the predicate form the first || the predicate from the
+   * second Descriptor to decide if an Atom should be selected.
+   */
   virtual bool predicate(std::pair<atomId_t,atom*>);
 …
 };
+/**
+ * Set Inversion of a Descriptor
+ */
 class AtomNotDescriptor_impl : public AtomDescriptor_impl
+{
 …
   virtual ~AtomNotDescriptor_impl();
+  /**
+   * Opposite of the given descriptor predicate.
+   */
   virtual bool predicate(std::pair<atomId_t,atom*>);

src/Patterns/Observer.hpp

-              ra1510d
+              rdbb474
 class Observable;
+/**
+ * An Observer is notified by all Observed objects, when anything changes.
+ *
+ * If a simple change is done to an Object the Obervable will call the update() method
+ * of all signed on observers, passing itself as a parameter for identification. The
+ * Observers should then react to the changes and update themselves accordingly.
+ *
+ * If an observed Object is destroyed it will call the subjectKilled() method
+ * of all signed on Observers, again passing itself as a parameter for identification.
+ * The Observers should handle the destruction of an observed Object gracefully, i.e.
+ * set themselves inactive, display something else, etc. There is no need
+ * to sign of from the dying object, since this will be handled by the Observable destructor.
+ */
 class Observer
+{
 …
 protected:
+  /**
+   * This method is called upon changes of the Observable
+   */
   virtual void update(Observable *publisher)=0;
+  /**
+   * This method is called when the observed object is destroyed.
+   */
   virtual void subjectKilled(Observable *publisher)=0;
 };
+/**
+ * An Observable implements all neccessary method for being observed.
+ *
+ * That is, it provides methods for signing on and of from an
+ * Observable that can be used by any observer. The actual
+ * observer-mechanism is handled at a central static place
+ * to avoid memory issues when many observable are around but only few
+ * are actually observed.
+ */
 class Observable : public Observer {
 public:
 …
   virtual ~Observable();
+  /**
+   * Sign an Observer on to this Observable. The Observer will be notified
+   * whenever something inside the Observable changes. The Observer can
+   * assign itself a priority for the changes in the range of -20:+20.
+   * The Observer with lower priority will be called before the others,
+   * same as with Unix nice-levels. This can be used when an Object
+   * contains other objects that observe it (derived values), and these objects have
+   * to recalculate their states before the changes should be propageted to the
+   * UI. A default priority of 0 should be fine in most cases, since there is
+   * ussually no need to order the update sequence.
+   */
   virtual void signOn(Observer *target, int priority=0);
+  /**
+   * Sign of a previously signed on Observer. After this no more
+   * updates will be recieved from that observer.
+   */
   virtual void signOff(Observer *target);
 …
   // Structure for RAII-Style notification
 protected:
+  /**
+   * This structure implements the Observer-mechanism RAII-Idiom.
+   * It triggers certain functions on creation and destruction so that
+   * Observer mechanisms can be linked to scope block.
+   */
   class _Observable_protector {
   public:

src/UIElements/MainWindow.hpp

-              ra1510d
+              rdbb474
 };
+/**
+ * The type of menuPopulators
+ */
 typedef void (*MenuMaker)(Menu*,MoleculeListClass*, config*, periodentafel*);
+/**
+ * This contains all Functions that are used to create the menus.
+ * Needs a specific funtion for each menu. All populators will be called
+ * by the UIFactory upon creation of the main menu. Thus the actuall construction
+ * of the Menus can be kept independent of the concrete type of UI that is being
+ * built.
+ */
 struct menuPopulaters{
   MenuMaker MakeEditMoleculesMenu;

src/UIElements/UIFactory.hpp

-              ra1510d
+              rdbb474
 struct menuPopulaters;
+/**
+ * Abstract Factory to create any kind of User interface object needed by the programm.
+ *
+ * The factory can be created and has to be set to a certain type upon creation. It will then
+ * only create UIelements of that certain type, so that all UIElements match. This way different
+ * UIs can be handled in a concise abstract way.
+ */
 class UIFactory
+{
 …
   virtual ~UIFactory();
+  // methods for creating UIElements
+  /**
+   * Produce some kind of main window, of whichever type was chosen when the factory was created
+   */
   virtual MainWindow* makeMainWindow(menuPopulaters,MoleculeListClass *, config *, periodentafel *, char *)=0;
+  /**
+   * Produce a User Interaction Dialog, that can query values from the User.
+   * Again the type is determined upon factory creation.
+   */
   virtual Dialog* makeDialog()=0;
 …
 public:
+  /**
+   * create a Factory of a certain type. From that moment on only those UIElements can be produced by the factory
+   */
   static void makeUserInterface(InterfaceTypes type);
+  /**
+   * get the previously created factory
+   */
   static UIFactory* get();
+  /**
+   * Destroy the created factory.
+   *
+   * Make sure that all UIElements that were created by the factory are destroyed before calling this method.
+   */
   static void purgeInstance();
 };

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset dbb474

Legend:

Download in other formats: