Add comments

include/tree.f90

@@ -1,15 +1,28 @@
 interface
 
+  !> Create a tree and return its pointer
+  !! @param tree_ctx     pointer to the tree
   subroutine Createtree_(tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     type(c_ptr), intent(out) :: tree_ctx
   end subroutine
 
+  !> Delete the tree and free memeory
+  !! @param tree_ctx     pointer to the tree
   subroutine DeleteTree(tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     type(c_ptr), intent(in) :: tree_ctx
   end subroutine
 
+  !> Get the node list for the tree
+  !! @param node_coord   coordinates of each tree node {x1,y1,z1,x2,y2,z2,...}
+  !! @param parent_lst   index of the parent node if it exists; -1 otherwise
+  !! @param child_lst    index of 8 child nodes if it has children; -1 otherwise
+  !! @param node_depth   depth of the tree node
+  !! @param node_ghost   1 if the node is a ghost node; 0 otherwise
+  !! @param node_leaf    1 if the node is a leaf  node; 0 otherwise
+  !! @param Nnodes       number of tree nodes
+  !! @param tree_ctx     pointer to the tree
   subroutine GetTree(node_coord, parent_lst, child_lst, node_depth, node_ghost, node_leaf, Nnodes, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     type(c_ptr), intent(out) :: node_coord  ! real*8, dimension(Nnode*3)
@@ -22,6 +35,13 @@ interface
     type(c_ptr), intent(in)  :: tree_ctx
   end subroutine
 
+  !> Change refinement of the tree
+  !! @param pt_coord         coordinates of the points
+  !! @param Npt              number of points
+  !! @param max_pts          maximum number of points per tree node
+  !! @param level_restrict   .true. to enable level restriction
+  !! @param periodic         .true. for periodic level restriction
+  !! @param tree_ctx         pointer to the tree
   subroutine UpdateRefinement(pt_coord, Npt, max_pts, level_restrict, periodic, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     real*8     , intent(in) :: pt_coord(*)
@@ -32,6 +52,13 @@ interface
     type(c_ptr), intent(in) :: tree_ctx
   end subroutine
 
+  !> Add some data to the tree nodes
+  !! @param data_name   name for the data
+  !! @param node_data   data array
+  !! @param Ndata       length of the data array
+  !! @param cnt         array of data-length for each node
+  !! @param Ncnt        length of cnt array (must be equal to #-of-nodes)
+  !! @param tree_ctx    pointer to the tree
   subroutine AddData(data_name, node_data, Ndata, cnt, Ncnt, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     character  , intent(in) :: data_name(*)
@@ -42,6 +69,13 @@ interface
     type(c_ptr), intent(in) :: tree_ctx
   end subroutine
 
+  !> Get node data from the tree
+  !! @param node_data   data array
+  !! @param Ndata       length of the data array
+  !! @param cnt         array of data-length for each node
+  !! @param Ncnt        length of cnt array (equal to #-of-nodes)
+  !! @param data_name   name for the data
+  !! @param tree_ctx    pointer to the tree
   subroutine GetData(node_data, Ndata, cnt, Ncnt, data_name, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     type(c_ptr), intent(out) :: node_data  ! real*8   , dimension(Ndata)
@@ -52,12 +86,19 @@ interface
     type(c_ptr), intent(in)  :: tree_ctx
   end subroutine
 
+  !> Delete node data from the tree
+  !! @param data_name   name for the data
+  !! @param tree_ctx    pointer to the tree
   subroutine DeleteData(data_name, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     character  , intent(in) :: data_name(*)
     type(c_ptr), intent(in) :: tree_ctx
   end subroutine
 
+  !> Write VTK output
+  !! @param fname       name of output file
+  !! @param show_ghost  .true. to show ghost nodes
+  !! @param tree_ctx    pointer to the tree
   subroutine WriteTreeVTK(fname, show_ghost, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     character  , intent(in) :: fname(*)
@@ -66,6 +107,11 @@ interface
   end subroutine
 
 
+  !> Add particles to the tree
+  !! @param pt_name     name of the particles
+  !! @param coord       coordinates of the particles {x1,y1,z1,x2,y2,...}
+  !! @param Npt         number of particles
+  !! @param tree_ctx    pointer to the tree
   subroutine AddParticles(pt_name, coord, Npt, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     character  , intent(in) :: pt_name
@@ -74,6 +120,13 @@ interface
     type(c_ptr), intent(in) :: tree_ctx
   end subroutine
 
+  !> Associate some data with the particles (for example charge density). The
+  !! data must be in the original order of the points.
+  !! @param pt_name     name of the particles
+  !! @param data_name   name of the data
+  !! @param pt_data     data array
+  !! @param Ndata       size of the data array
+  !! @param tree_ctx    pointer to the tree
   subroutine AddParticleData(data_name, pt_name, pt_data, Ndata, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     character  , intent(in) :: data_name(*)
@@ -83,20 +136,34 @@ interface
     type(c_ptr), intent(in) :: tree_ctx
   end subroutine
 
-  subroutine GetParticleData(pt_data, N, data_name, tree_ctx)
+  !> Get data associated with the particles. The output array will be ordered
+  !! according to the original ordering of the points
+  !! @param pt_data     data array
+  !! @param Ndata       size of the data array
+  !! @param data_name   name of the data
+  !! @param tree_ctx    pointer to the tree
+  subroutine GetParticleData(pt_data, Ndata, data_name, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     type(c_ptr), intent(out) :: pt_data    ! real*8, dimension(N)
-    integer*4  , intent(out) :: N
+    integer*4  , intent(out) :: Ndata
     character  , intent(in)  :: data_name(*)
     type(c_ptr), intent(in)  :: tree_ctx
   end subroutine
 
+  !> Delete data associated with a particle (or a particle and all its data)
+  !! @param data_name   name of the data (or particle)
+  !! @param tree_ctx    pointer to the tree
   subroutine DeleteParticleData(data_name, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     character  , intent(in) :: data_name
     type(c_ptr), intent(in) :: tree_ctx
   end subroutine
 
+  !> Write VTK output
+  !! @param fname       name of output file
+  !! @param data_name   name of the data
+  !! @param show_ghost  .true. to show ghost nodes
+  !! @param tree_ctx    pointer to the tree
   subroutine WriteParticleVTK(fname, data_name, show_ghost, tree_ctx)
     use, intrinsic :: ISO_C_BINDING
     character  , intent(in) :: fname(*)