Robodoc Standards FLASH3

Robodocing Functions:

Always put a robodoc function header just before the function it documents. Use the letter 'f' for the robodoc type for every function, whether it is a c function, a fortran function, or a fortran subroutine. The name of the header (on the first line of the comment) is composed of the name of the FLASH unit in which the function resides and the name of the function. The header name indicates the place where the function logically falls in the FLASH component (unit) structure. The name here is the filename as well as the function name. The FLASH unit path should start at the FLASH directory root, for example, source/Grid/Grid_getCellCoords. A 'codeCheck' script runs nightly and reports to the website documentation and other violations.

Function Header Sections:

Put the header sections in the following order:
NAME (mandatory)
SYNOPSIS (mandatory)
DESCRIPTION (mandatory)
ARGUMENTS (mandatory)
PARAMETERS (mandatory if describing an Unit_init file)
RESULT (optional)
EXAMPLE (optional)
SIDE EFFECTS (optional)
NOTES (optional)
SEE ALSO (optional)

This is similar to man page section order.

The NAME section contains the name of the function.

The SYNOPSIS section indicates how the function is called including the order and type of arguments and their intent (in) or (out) or (inout). In order for the synopsis to be parsed witht the codeCheck script where the the actual routine arguments are compared against the arguments given in the synopsis header, a double colon '::' must be used to separate the variable type with the variable name. See example below for exact syntax.

The DESCRIPTION section should go into detail about how the function works and how it is used. This lets the user know what to expect from the operation of the function. It could include a description of side effects or those could be broken off in their own sections. Describe the algorithm used.

The ARGUMENTS section contains the list of arguments to the function with a short description for each. A '-' or a ':' must be used to separate the variable name from the description in order to be parsed by the codeCheck script. See description below.

The PARAMETERS section indicates which FLASH runtime parameters are used by the function. In FLASH3 parameters are only fetched in Unit_init routines and so the PARAMETERS header should only be used in these routines. Do not use this for the function arguments.

The RESULTS section should be for functions that return something, like a fortran subroutine that modifies an argument or a fortran function.

Below is an example of a robodoc header for a subroutine. The header documents the Grid_getCellCoords function in the source/Grid unit.


!!****f* source/Grid/Grid_getCellCoords
!!!
! NAME
!! Grid_getCellCoords
!!
!! SYNOPSIS
!!
!! Grid_getCellCoords(integer(IN) :: axis,
!! integer(IN) :: blockid,
!! integer(IN) :: edge,
!! logical(IN) :: guardcell,
!! real(OUT) :: coordinates(size),
!! integer(IN) :: size)
!!
!! DESCRIPTION
!!
!! This subroutine is an accessor function that gets the coordinates of
!! the cells in a given block.
!! Coordinates are retrieved one axis at a time,
!! meaning you can get the i, j, _or_ k coordinates with one call.
!! If you want all the coordinates, all axises, you
!! need to call Grid_getCellCoords 3 times, one for each axis.
!! The code carries coordinates at three points in each direction for
!! each cell. These are LEFT_EDGE, CENTER and the RIGHT_EDGE
!!
!!
!!
!! ARGUMENTS
!!
!! axis - specifies the integer index coordinates of the cells being retrieved.
!! axis can have one of three different values, IAXIS, JAXIS or KAXIS
!! (defined in constants.h as 1,2 and 3)
!!
!! blockId - integer block number
!!
!! edge - integer value with one of three values,
!! LEFT_EDGE, RIGHT_EDGE or CENTER
!! The edge argument specifies what side of the zone to get, the CENTER
!! point, the LEFT_EDGE or the RIGHT_EDGE of the zone.
!!
!! guardcell - logical input. If true coordinates for guardcells are returned
!! along with the interior cells, if false, only the interior coordinates
!! are returned.
!!
!!
!! coordinates - The array holding the data returning the coordinate values
!! coordinates is of size (see below)
!!
!! size - integer array specifying the size of the coordinates array.
!! If guardcell true then the size = number of interior cells + 2*guardcells
!! otherwise size = number of interior cells
!! EXAMPLES
!!
!! This is where you can place examples explainint the functionality of the routine
!!
!! NOTES
!! variables that start with "gr_" are variables of Grid unit scope
!! and are stored in the fortran module Grid_data. Variables are not
!! starting with gr_ are local varibles or arguments passed to the
!! routine.
!!
!!***

Internal routines that are not in the API are documented by giving an 'if' in the robodocs header. See below.

!!****if* source/Grid/GridParticles/Paramesh/gr_moveParticlesUpOffProc
!!
!! NAME
!! gr_moveParticlesUpOffProc
!!
!! SYNOPSIS
!!
!! gr_moveParticlesUpOffProc( real(inout) :: particles(NPART_PROPS, maxParticles),
!! integer(inout) :: localNumParticles,
!! integer (in) :: maxParticlesPerProc,
!! integer(in) :: binMoveOffProc(3,maxParticlesPerProc),
!! integer (in) :: numParticlesToMove,
!! integer (in) :: thisLevel,
!! integer(in) :: mandatoryProcSendList(:),
!! integer(in) :: sendListCount)
!
!!
!! DESCRIPTION
!!
!! Move particles from the current block to a parent who is off current processor
!!
!! To avoid a global communication call where each processor has to know if it is
!! receiving particles or not, a processor with a parent will post a receive from all procs
!! that hold one or more of its children, whether or not that child has particles to
!! send or not. On the flip side each processor with a child who has a parent off
!! the current processor must send something to the off proc parent. If the child does
!! not have particles to send, then a dummy value is sent.
!!
!! General idea of algorithm
!!
!! 1. Determine parent processors that must receive something (either a particle or a dummy)
!!
!! 2. Post the MPI_Irecv calls (non blocking)
!!
!! 3. Go through the mandatoryProcSendList and determine how many particles, (if any) need
!! to be sent to a current processor
!!
!! 4. Put the particles in a buffer and call MPI_send (blocking)
!!
!! 5. Pack the particles, meaning remove any 'empty' space in the particles data structure
!! left by a particle that has moved off the current processor
!!
!! 6. Wait for all the particles to be received by their appropriate processors call MPI_Wait
!! (might be able to use MPI_WaitAll)
!!
!! 7. Add the received particles to the particles data structure
!!
!!
!! ARGUMENTS
!!
!! particles - List of particles on this processor.
!! It is two dimensional real array, the first dimension
!! represents each particle's properties, and second dimension is index to
!! particles.
!!
!! localnumParticles - While coming in it contains the current number of particles mapped to
!! this processor. After all the data structure movement, the number
!! of local particles might change, and the new value is put back into it
!!
!! maxParticlesPerProc - This is parameter determined at runtime, and is the maximum number of local
!! particles that a simulation expects to have. All the arrays in the particles
!! unit are allocated based on this number
!!
!! binMoveOffProc - An integer array of information indicating which particles need to move off
!! this processor. A two-dimensional array. The first dimension shows the information
!! needed to move:
!! binMoveOffProc(1,i) -- parent block number
!! binMoveOffProc(2,i) -- parent processor number
!! binMoveOffProc(3,i) -- order within processor array of particles
!! The second dimension indexes the values within binMoveOffProc
!!
!! numParticlesToMove - Number of particles that are being moved off processor
!! Filled size of binMoveOffProc
!!
!! thisLevel - current level in AMR refinement tree of operation; moving particles UP off here
!!
!!
!! mandatoryProcSendList - list of UNIQUE parent processors which must have particles
!! (or a particle dummy) sent to it
!!
!!
!! sendListCount - the number of UNIQUE parent processors which must have a
!! particle (or a particle dummy) sent to it.
!!
!!
!!
!! NOTES
!!
!! This routine needs more extensive testing
!!
!!***


Include files can also be documented with robodocs, although most
likely they have fewer headers in them. The 'h' character identifies
the file as an include file to robodocs.

!!****h* source/Particles/Particles.h
!!
!! NAME
!!
!! Particles.h
!!
!! DESCRIPION
!!
!! This is the header file for the Particles module. It includes general
!! parameters that any routines calling these interfaces needs to
!! understand.
!!
!!***