This file describes the scripts used to add missing comments and parse existing comments
for subroutines and functions in CP2K. The objective of the script(s) is to ensure that 
all subroutines and functions in CP2K have a standard DOXYGEN comment block and to flag 
any missing comments such that the CP2K developers can add/update these when time is
available. 

The driver script doxyify.sh will process CP2K source code (*.F files) files  
processing one file at a time. The following steps are carried out for each *.F file: 

1. Run remove_double_ampersands.pl - removes any any double ampersand characters
2. Run fixcomments.pl - does the addition of missing comments or updating of existing comments
3. Run remove_extra_comments.pl - removes any extra comment lines which arise from application 
of fixcomments.pl
4. Finally, overwrite the original *.F file with the updated version

To run the script you should execute it with the name of the source file you want to 
process or a list of files e.g. 

./doxyify.sh full_path_to_cp2k_src/myfile.F # Processes one file
./doxyify.sh full_path_to_cp2k_src/myfile.F full_path_to_cp2k_src/myfile2.F full_path_to_cp2k_src/myfile2.F # Processes multiple files

In debug mode, the script will produce a lot of output if the whole source tree is processed so you may 
wish to redirect the stdout to file, e.g. 

./doxyify.sh > comments.txt


*******************************
* remove_double_ampersands.pl *
*******************************

Removes any double ampersand characters that occur at the end of one line and the start of
the next line, e.g: 

 SUBROUTINE fred(a,b, &
     & c,d)

becomes 

 SUBROUTINE fred(a,b, &
       c,d)

This is performed throughout the source code and is necessary as the ampersand is used 
by fixcomments.pl to determine whether a subroutine/function definition extends across 
multiple lines. 


******************
* fixcomments.pl *
******************
The script adds in missing comments and parses existing comments checking whether any data
is missing. For procedures with no existing comments, e.g. a subroutine with 3 arguments a, b
and c: 

SUBROUTINE fred (a,b,c)

will be updated to (the ... are to indicate comments are required)
! *****************************************************************************
!> \brief ...
!> \param a ...
!> \param b ...
!> \param c ...
! *****************************************************************************
SUBROUTINE fred (a,b,c)

The scripts works as follows. 

We read through the source file until we see a comment block e.g. something beginning 
with !> 

We then loop over the comment block looking for entries for \brief, \param, \date, 
\par, \version and \note and \author. If any of these items exist we store the details 
in separate variables. We also keep a copy of the entire comment block in the oldheader 
variable as we need to print the comment block out unchanged for MODULE and TYPE. When 
parsing the header we ensure that we don't throw any text away. 

Once the comment block has been read in we continue reading in the code line by line. 
If we don't encounter any procedures then the output file will be identical to the 
input file. 

However, if we encounter a procedure we then read in the line(s) containing the
definition, e.g. 

SUBROUTINE fred(a,b,c) 

to an array called @string. We do this by splitting over space, comma, brackets etc. We 
also take into account of the fact a subroutine / function definition can extend over multiple 
lines via the ampersand (&) character and ampersand variable. The @string array then contains
the type of procedure, its name and the arguments, e.g. for the example above @string would
contain 5 elements: SUBROUTINE, fred, a, b, c. 

Once we know the name and arguments of the procedure we loop over the arguments checking 
to see whether the comment block contained a match. If it is does we use the existing text, 
if no match is found then the standard text detailed above is output. We also check whether 
any text exists for the \brief entry and re-use this if available, otherwise the \brief ... 
text is added as detailed above. The script can also handle \date, \par, \author, \note and 
\version entries if these should be required in future. At present these entries are copied 
across unchanged if they exist and otherwise they are not added in. 

Finally anything else that was found in the comment block is output and suitably annotated. 
For example unmatched procedure arguments are flagged up, lines which begin with !> , !, or 
!> \something_or_other are also annotated. 

The annotations used for marking up the comment block are as follows:

... Added to \brief and \param only if no existing information is available. Other 
commonly occurring entries such as \par, \author, \version, \note and \date if they exist 
are passed through unchanged. 

UNMATCHED_PROCEDURE_ARGUMENT - gets appended on to any procedure arguments in the comment block 
that don't match those in the procedure definition. 

UNKNOWN_DOXYGEN_COMMENT - for parts of the comment block which look like a standard Doxygen 
block (e.g. lines that look like: "!> \something or other") but not part of the standard 
header above. 

UNKNOWN_COMMENT - lines that begin !> or ! inside the comment block. These get placed into 
a !> \note with UNKNOWN_COMMENT added at the start of the line. 

The script also includes checks to ensure that the annotations are not added to a line 
multiple times.

****************************
* remove_extra_comments.pl *
****************************
Post-processing script to remove any double lines which begin ! ******
e.g. 

! *****************************************************************************
! *****************************************************************************

gets changed to 

! *****************************************************************************

This is necessary because occasionally a procedure may be missing the start 
or end ! **** line or may have a duplicate one. 

