Merge pull request #34 from MFraters/add_documentation_and_copyright_…

…notices

Add more documetation and add copyright notices to files which still missed them.

app/main.cc

@@ -1,3 +1,22 @@
+/*
+  Copyright (C) 2018 by the authors of the World Builder code.
+
+  This file is part of the World Builder.
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU Lesser General Public License as published
+   by the Free Software Foundation, either version 2 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public License
+   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
 #include <exception>
 #include <iostream>
 

doc/doxygen_config.dox

@@ -62,7 +62,7 @@ LOOKUP_CACHE_SIZE      = 0
 # Build related configuration options
 #---------------------------------------------------------------------------
 EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 EXTRACT_PACKAGE        = NO
 EXTRACT_STATIC         = NO
 EXTRACT_LOCAL_CLASSES  = YES

include/world_builder/coordinate_systems/cartesian.h

@@ -48,8 +48,9 @@ namespace WorldBuilder
         ~Cartesian();
 
         /**
-         * Read in the world builder file
+         * Read in the world builder file, and does parsing and preparation for the model to start.
          */
+        // Todo: might have to rename this function, or split it up.
         virtual
         void decare_entries();
 

include/world_builder/coordinate_systems/interface.h

@@ -50,8 +50,9 @@ namespace WorldBuilder
         ~Interface();
 
         /**
-         * read in the world builder file
+         * Read in the world builder file, and does parsing and preparation for the model to start.
          */
+        // Todo: might have to rename this function, or split it up.
         virtual
         void decare_entries() = 0;
 
@@ -104,7 +105,7 @@ namespace WorldBuilder
 
 
     /**
-     * factory function
+     * A factory function for creating coordinate systems.
      */
     std::unique_ptr<Interface>
     create_coordinate_system(const std::string name, World *world);

include/world_builder/coordinate_systems/spherical.h

@@ -48,8 +48,9 @@ namespace WorldBuilder
         ~Spherical();
 
         /**
-         * Read in the world builder file
+         * Read in the world builder file, and does parsing and preparation for the model to start.
          */
+        // Todo: might have to rename this function, or split it up.
         virtual
         void decare_entries();
 

include/world_builder/features/continental_plate.h

@@ -56,7 +56,8 @@ namespace WorldBuilder
 
 
         /**
-         * Returns a temperature based on the given position
+         * Returns a temperature based on the given position, depth in the model,
+         * gravity and current temperature.
          */
         virtual
         double temperature(const Point<3> &position,
@@ -66,7 +67,9 @@ namespace WorldBuilder
 
         /**
          * Returns a value for the requests composition (0 is not present,
-         * 1 is present) based on the given position and
+         * 1 is present) based on the given position, depth in the model,
+         * the composition which is being requested and the current value
+         * of that composition at this location and depth.
          */
         virtual
         double composition(const Point<3> &position,

include/world_builder/features/interface.h

@@ -113,7 +113,7 @@ namespace WorldBuilder
 
 
     /**
-     * factory function
+     * A factory function for creating features.
      */
     std::unique_ptr<Interface>
     create_feature(const std::string name, WorldBuilder::World *world);

include/world_builder/features/oceanic_plate.h

@@ -30,7 +30,7 @@ namespace WorldBuilder
   {
 
     /**
-     * This class represents a continental plate and can implement submodules
+     * This class represents a oceanic plate and can implement submodules
      * for temperature and composition. These submodules determine what
      * the returned temperature or composition of the temperature and composition
      * functions of this class will be.
@@ -56,7 +56,8 @@ namespace WorldBuilder
 
 
         /**
-         * Returns a temperature based on the given position
+         * Returns a temperature based on the given position, depth in the model,
+         * gravity and current temperature.
          */
         virtual
         double temperature(const Point<3> &position,
@@ -66,7 +67,9 @@ namespace WorldBuilder
 
         /**
          * Returns a value for the requests composition (0 is not present,
-         * 1 is present) based on the given position and
+         * 1 is present) based on the given position, depth in the model,
+         * the composition which is being requested and the current value
+         * of that composition at this location and depth.
          */
         virtual
         double composition(const Point<3> &position,

include/world_builder/features/subducting_plate.h

@@ -30,7 +30,7 @@ namespace WorldBuilder
   {
 
     /**
-     * This class represents a continental plate and can implement submodules
+     * This class represents a subducting plate and can implement submodules
      * for temperature and composition. These submodules determine what
      * the returned temperature or composition of the temperature and composition
      * functions of this class will be.
@@ -56,7 +56,8 @@ namespace WorldBuilder
 
 
         /**
-         * Returns a temperature based on the given position
+         * Returns a temperature based on the given position, depth in the model,
+         * gravity and current temperature.
          */
         virtual
         double temperature(const Point<3> &position,
@@ -66,7 +67,9 @@ namespace WorldBuilder
 
         /**
          * Returns a value for the requests composition (0 is not present,
-         * 1 is present) based on the given position and
+         * 1 is present) based on the given position, depth in the model,
+         * the composition which is being requested and the current value
+         * of that composition at this location and depth.
          */
         virtual
         double composition(const Point<3> &position,
@@ -87,8 +90,25 @@ namespace WorldBuilder
         // relevant data could be stored in the cache. But this
         // not a urgent problem, and would require testing.
 
+        /**
+         * This variable stores the depth at which the subducting
+         * plate starts. It makes this depth effectively the surface
+         * of the model for the slab.
+         */
         double starting_depth;
+
+        /**
+         * The depth which below the subducting plate may no longer
+         * be present. This can not only help setting up models with
+         * less effort, but can also improve performance, because
+         * the algorithm doesn't have to search in locations below
+         * this depth.
+         */
         double maximum_depth;
+
+        /**
+         * A point on the surface to which the subducting plates subduct.
+         */
         Point<2> reference_point;
 
         std::vector<std::vector<double> > slab_segment_lengths;

include/world_builder/parameters.h

@@ -195,6 +195,8 @@ namespace WorldBuilder
        * Returns the array with pointers to the requested type. The reason a
        * raw pointer is returned is that caller is not responsible for the
        * classes pointed at in the return vector or has ownership on them.
+       * This function is currently implemented for the Types Double, Segment,
+       * ConstantLayer, Point2D and Point3D.
        * \param name The key where the variable is stored. The array contains
        * \return std::vector<T*>
        */
@@ -226,8 +228,8 @@ namespace WorldBuilder
       ptree tree;
 
       /**
-       * This variable ontains a pointer to the a part of the tree. This
-       * variable is not repsonsible for the tree, so using a raw pointer.
+       * This variable contains a pointer to the a part of the tree. This
+       * variable is not responsible for the tree, so using a raw pointer.
        * @see tree
        */
       ptree *local_tree;

include/world_builder/types/interface.h

@@ -65,18 +65,6 @@ namespace WorldBuilder
         type get_type() const;
 
 
-        /**
-         * read in the world builder file
-         */
-        //virtual
-        //Interface* get_inner_type() const ;
-
-        /**
-         * read in the world builder file
-         */
-        //virtual
-        //Interface* set_inner_type();
-
       protected:
         type type_name;
     };

include/world_builder/utilities.h

@@ -242,8 +242,30 @@ namespace WorldBuilder
     /**
      * Computes the distance of a point to a curved plane.
      * TODO: add more info on how this works/is implemented.
-     * \param point This is the point of which we want to know the distance to the curved planes
-     * \param point_list This is a list of 2d Points
+     * \param point This is the cartesian point of which we want to know the
+     * distance to the curved planes
+     * \param reference_point This is a 2d point in natural coordinates at the
+     * surface which the curved planes dip towards. Natural coordinates are in
+     * cartesian (x,y,z) in meters and in spherical radius in meters and longitude
+     * and latitude in radians.
+     * \param point_list This is a vector of 2d Points in natural coordinates at the
+     * surface which define the line along the surface at which the curved planes
+     * start. Natural coordinates are in cartesian (x,y,z) in meters and in spherical
+     * radius in meters and longitude and latitude in radians.
+     * \param plane_segment_lengths This is a vector of vectors of doubles. It contains
+     * the length of every segment at point in the point_list (in the same order as
+     * the point_list.
+     * \param plane_segment_angles This is a vector of vectors of 2d points. It contains
+     * the begin and end angle of every segment at point in the point_list (in the same
+     * order as the point_list.
+     * \param start_depth This value contains the depth at which the plane starts. This
+     * means that the start_depth effectively becomes the surface for this slab.
+     * \param coordinate_system This is a reference to the coordinate system of the
+     * World Builder. This is used to convert cartesian to natural coordinates and back.
+     * \param only_positive This value deterines whether only the the part below the
+     * plane should count as distance or both sides of the plane. It is called only_positive
+     * because the area below the plane, the distance is positve, and above the plane the
+     * distance is negative.
      */
     std::map<std::string,double> distance_point_from_curved_planes(const Point<3> &point,
                                                                    const Point<2> &reference_point,

include/world_builder/world.h

@@ -54,13 +54,28 @@ namespace WorldBuilder
        */
       void declare_and_parse(Parameters &parameters);
 
+      /**
+       * Returns the temperature based on a 2d Cartesian point, the depth in the
+       * model at that point and the gravity norm at that point.
+       */
       double temperature(const std::array<double, 2> &point, const double depth, const double gravity_norm) const;
 
+      /**
+       * Returns the temperature based on a 3d Cartesian point, the depth in the
+       * model at that point and the gravity norm at that point.
+       */
       double temperature(const std::array<double, 3> &point, const double depth, const double gravity_norm) const;
 
-
+      /**
+       * Returns the composition value based on a 2d Cartesian point, the depth in
+       * the model at that point and the gravity norm at that point.
+       */
       double composition(const std::array<double, 2> &point, const double depth, const unsigned int composition_number) const;
 
+      /**
+       * Returns the composition value based on a 3d Cartesian point, the depth in
+       * the model at that point and the gravity norm at that point.
+       */
       double composition(const std::array<double, 3> &point, const double depth, const unsigned int composition_number) const;
 
       /**
@@ -69,9 +84,19 @@ namespace WorldBuilder
       static const char path_seperator = '.';
 
 
+      /**
+       * This is the parameter class, which stores all the values loaded in
+       * from the parameter file or which are set directly.
+       */
       Parameters parameters;
 
     private:
+      /**
+       * The minimum dimension. If cross section data is provided, it is set
+       * to 2, which means the 2d function of temperature and composition can
+       * be used. Otherwise it is set to 3, which means that they can't be
+       * used.
+       */
       unsigned int dim;
 
 

include/world_builder/wrapper_c.h

@@ -21,16 +21,41 @@
 #define _world_builder_wrapper_c_h
 
 extern "C" {
+  /**
+   * This function creates an object of the world builder and returns a pointer
+   * to it. This pointer can then be used to call the temperature and composition
+   * functions. When done call the release world function to destroy the object.
+   */
   void create_world(void **ptr_ptr_world, const char *world_builder_file);
 
+  /**
+   * This function return the temperature at a specific location given x, z, depth and
+   * gravity.
+   */
   void temperature_2d(void *ptr_ptr_world, double x, double z, double depth, double gravity, double *temperature);
 
+  /**
+   * This function return the temperature at a specific location given x, y, z, depth and
+   * gravity.
+   */
   void temperature_3d(void *ptr_ptr_world, double x, double y, double z, double depth, double gravity, double *temperature);
 
+  /**
+   * This function return the composition at a specific location given x, z, depth and
+   * composition number.
+   */
   void composition_2d(void *ptr_ptr_world, double x, double z, double depth, unsigned int composition_number, double *composition);
 
+  /**
+   * This function return the composition at a specific location given x, y, z, depth and
+   * composition number.
+   */
   void composition_3d(void *ptr_ptr_world, double x, double y, double z, double depth, unsigned int composition_number, double *composition);
 
+  /**
+   * The destructor for the world builder class. Call this function when done with the
+   * world builder.
+   */
   void release_world(void *ptr_ptr_world);
 }
 

source/parameters.cc

@@ -871,10 +871,35 @@ namespace WorldBuilder
     return collapse.substr(0,collapse.size()-path_seperator.size());
   }
 
+  /**
+   * Returns a vector of pointers to the Double Type based on the provided name.
+   * Note that the variable with this name has to be loaded before this function is called.
+   */
   template const std::vector<const Types::Double * > Parameters::get_array<const Types::Double >(const std::string &name) const;
+
+  /**
+   * Returns a vector of pointers to the Segment Type based on the provided name.
+   * Note that the variable with this name has to be loaded before this function is called.
+   */
   template const std::vector<const Types::Segment * > Parameters::get_array<const Types::Segment >(const std::string &name) const;
+
+  /**
+   * Returns a vector of pointers to the ConstantLayer Type based on the provided name.
+   * Note that the variable with this name has to be loaded before this function is called.
+   */
   template const std::vector<const Types::ConstantLayer * > Parameters::get_array<const Types::ConstantLayer >(const std::string &name) const;
+
+  /**
+   * Returns a vector of pointers to the Point<2> Type based on the provided name.
+   * Note that the variable with this name has to be loaded before this function is called.
+   */
   template const std::vector<const Types::Point<2>* > Parameters::get_array<const Types::Point<2> >(const std::string &name) const;
+
+  /**
+   * Returns a vector of pointers to the Point<3> Type based on the provided name.
+   * Note that the variable with this name has to be loaded before this function is called.
+   */
   template const std::vector<const Types::Point<3>* > Parameters::get_array<const Types::Point<3> >(const std::string &name) const;
+
 }