Update papi_hl_output_writer.py to use 4 spaces instead of 2 for code…

… formatting and add Doxygen

documentation to classes and functions.

doc/Doxyfile-common

@@ -628,7 +628,7 @@ INPUT_ENCODING         = UTF-8
 # *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py
 # *.f90 *.f *.for *.vhd *.vhdl
 
-FILE_PATTERNS          = *.c *.h
+FILE_PATTERNS          = *.c *.h *.py
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
 # should be searched for input files as well. Possible values are YES and NO.
@@ -1719,3 +1719,9 @@ GENERATE_LEGEND        = NO
 # the various graphs.
 
 DOT_CLEANUP            = YES
+
+# By default Python docstrings are displayed as preformmated text 
+# and Doxygen's special commands cannot be used. By setting PYTHON_DOCSTRING
+# to NO the Doxygen's special commands can be used and the contents of the
+# docstring documentation blocks is shown as Doxygen documentation.
+PYTHON_DOCSTRING       = NO

doc/Doxyfile-man3

@@ -20,9 +20,9 @@
 # with spaces.
 
 INPUT					= ../src/papi.h  ../src/papi.c ../src/high-level/papi_hl.c \
-							../src/papi_fwrappers.c
+					  ../src/papi_fwrappers.c ../src/high-level/scripts/papi_hl_output_writer.py
 
-FILE_PATTERNS          = *.c *.h
+FILE_PATTERNS          = *.c *.h *.py
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
 # should be searched for input files as well. Possible values are YES and NO.

man/man3/papi_hl_output_writer_Sum_Counter.3

@@ -0,0 +1,106 @@
+.TH "papi_hl_output_writer.Sum_Counter" 3 "Wed Oct 2 2024 22:49:41" "Version 7.2.0.0b1" "PAPI" \" -*- nroff -*-
+.ad l
+.nh
+.SH NAME
+papi_hl_output_writer.Sum_Counter \- \fBSum_Counter\fP class defintion\&.  
+
+.SH SYNOPSIS
+.br
+.PP
+.PP
+Inherits object\&.
+.SS "Public Member Functions"
+
+.in +1c
+.ti -1c
+.RI "\fB__init__\fP (self)"
+.br
+.RI "\fBSum_Counter\fP class initializer\&. "
+.ti -1c
+.RI "\fBadd_event\fP (self, value)"
+.br
+.RI "Method definition for add_event\&. "
+.ti -1c
+.RI "\fBget_min\fP (self)"
+.br
+.RI "Method definition for get_min\&. "
+.ti -1c
+.RI "\fBget_median\fP (self)"
+.br
+.RI "Method definition for get_median\&. "
+.ti -1c
+.RI "\fBget_sum\fP (self)"
+.br
+.RI "Method definition for get_sum\&. "
+.ti -1c
+.RI "\fBget_max\fP (self)"
+.br
+.RI "Method definition for get_max\&. "
+.in -1c
+.SS "Data Fields"
+
+.in +1c
+.ti -1c
+.RI "\fBmin\fP"
+.br
+.ti -1c
+.RI "\fBall_values\fP"
+.br
+.ti -1c
+.RI "\fBmax\fP"
+.br
+.in -1c
+.SH "Detailed Description"
+.PP 
+Calculates the min, max, median or sum for the measurements of a recorded events\&. 
+.SH "Member Function Documentation"
+.PP 
+.SS "papi_hl_output_writer\&.Sum_Counter\&.add_event ( self,  value)"
+Add a recorded event and measurement to summary output\&.
+.PP
+\fBParameters\fP
+.RS 4
+\fIvalue\fP Measurement from a recorded event\&. E\&.g\&. PAPI_TOT_INS\&. 
+.RE
+.PP
+
+.SS "papi_hl_output_writer\&.Sum_Counter\&.get_max ( self)"
+Calculate the maximum for a set of measurements for a recorded event\&.
+.PP
+\fBReturns\fP
+.RS 4
+The maximum for a set of measurement values for a recorded event\&. E\&.g\&. PAPI_TOT_INS\&. 
+.RE
+.PP
+
+.SS "papi_hl_output_writer\&.Sum_Counter\&.get_median ( self)"
+Calculates the median for a set of measurements for a recorded event\&.
+.PP
+\fBReturns\fP
+.RS 4
+The median for a set of measurement values for a recorded event\&. E\&.g\&. PAPI_TOT_INS\&. 
+.RE
+.PP
+
+.SS "papi_hl_output_writer\&.Sum_Counter\&.get_min ( self)"
+Calculates the minimum for a set of measurements for a recorded event\&.
+.PP
+\fBReturns\fP
+.RS 4
+The minimum for a set of measurement values for a recorded event\&. E\&.g\&. PAPI_TOT_INS\&. 
+.RE
+.PP
+
+.SS "papi_hl_output_writer\&.Sum_Counter\&.get_sum ( self)"
+Calculates the sum for a set of measurements for a recorded event\&.
+.PP
+\fBReturns\fP
+.RS 4
+The sum of measurement values for a recorded event\&. E\&.g\&. PAPI_TOT_INS\&. 
+.RE
+.PP
+
+
+.SH "Author"
+.PP 
+Generated automatically by Doxygen for PAPI from the source code\&.

man/man3/papi_hl_output_writer_Sum_Counters.3

@@ -0,0 +1,83 @@
+.TH "papi_hl_output_writer.Sum_Counters" 3 "Wed Oct 2 2024 22:49:42" "Version 7.2.0.0b1" "PAPI" \" -*- nroff -*-
+.ad l
+.nh
+.SH NAME
+papi_hl_output_writer.Sum_Counters \- \fBSum_Counters\fP class defintion\&.  
+
+.SH SYNOPSIS
+.br
+.PP
+.PP
+Inherits object\&.
+.SS "Public Member Functions"
+
+.in +1c
+.ti -1c
+.RI "\fB__init__\fP (self)"
+.br
+.RI "\fBSum_Counters\fP class initializer\&. "
+.ti -1c
+.RI "\fBadd_region\fP (self, rank_id, thread_id, events=OrderedDict())"
+.br
+.RI "Method defintion for add_region\&. "
+.ti -1c
+.RI "\fBget_json\fP (self)"
+.br
+.RI "Method definition for get_json\&. "
+.in -1c
+.SS "Data Fields"
+
+.in +1c
+.ti -1c
+.RI "\fBregions\fP"
+.br
+.ti -1c
+.RI "\fBregions_last_rank_id\fP"
+.br
+.ti -1c
+.RI "\fBregions_rank_num\fP"
+.br
+.ti -1c
+.RI "\fBregions_last_thread_id\fP"
+.br
+.ti -1c
+.RI "\fBregions_thread_num\fP"
+.br
+.ti -1c
+.RI "\fBclean_regions\fP"
+.br
+.ti -1c
+.RI "\fBsum_counters\fP"
+.br
+.in -1c
+.SH "Detailed Description"
+.PP 
+Gathers summary output for a region (e\&.g\&. computation) and accompanying measurements for a recorded event (e\&.g\&. PAPI_TOT_INS)\&. 
+.SH "Member Function Documentation"
+.PP 
+.SS "papi_hl_output_writer\&.Sum_Counters\&.add_region ( self,  rank_id,  thread_id,  events = \fROrderedDict()\fP)"
+Adds the region (e\&.g\&. computation) and accompanying measurements for a recorded event (e\&.g\&. PAPI_TOT_INS) to summary output\&.
+.PP
+\fBParameters\fP
+.RS 4
+\fIrank_id\fP MPI rank, if no MPI rank is present this value will be random\&. 
+.br
+\fIthread_id\fP Thread identifier containing performance events\&. E\&.g\&. 0\&. 
+.br
+\fIevents\fP An ordered dictionary containing measurements for recorded events obtained through PAPI HL function calls\&. E\&.g\&. PAPI_TOT_INS\&. 
+.RE
+.PP
+
+.SS "papi_hl_output_writer\&.Sum_Counters\&.get_json ( self)"
+Calculates the min, max, median, or sum for a set of measurements for a recorded event\&. E\&.g\&. PAPI_TOT_INS\&.
+.PP
+\fBReturns\fP
+.RS 4
+An ordered dictionary containing summary measurements for recorded events\&. E\&.g\&. PAPI_TOT_INS\&. 
+.RE
+.PP
+
+
+.SH "Author"
+.PP 
+Generated automatically by Doxygen for PAPI from the source code\&.