Add: developer documentation to new files

Author: LKedward

src/fpm_backend_console.f90

@@ -1,3 +1,13 @@
+!># Build Backend Console
+!> This module provides a lightweight implementation for printing to the console
+!> and updating previously-printed console lines. It used by `[[fpm_backend_output]]`
+!> for pretty-printing build status and progress.
+!>
+!> @note The implementation for updating previous lines relies on no other output
+!> going to `stdout`/`stderr` except through the `console_t` object provided.
+!>
+!> @note All write statements to `stdout` are enclosed within OpenMP `critical` regions
+!>
 module fpm_backend_console
 use iso_fortran_env, only: stdout=>output_unit
 implicit none
@@ -7,22 +17,34 @@ module fpm_backend_console
 
 character(len=*), parameter :: ESC = char(27)
 
+!> Console object
 type console_t
+    !> Number of lines printed
     integer :: n_line = 1
+    !> 'Plain' output (no escape codes)
     logical :: plain_mode = .false.
+    !> Escape code for erasing current line
     character(:), allocatable :: LINE_RESET
+    !> Escape code for moving up one line
     character(:), allocatable :: LINE_UP
+    !> Escape code for moving down one line
     character(:), allocatable :: LINE_DOWN
 contains
+    !> Initialise the console object
     procedure :: init => console_init
+    !> Write a single line to the console
     procedure :: write_line => console_write_line
+    !> Update a previously-written console line
     procedure :: update_line => console_update_line
 end type console_t
 
 contains
 
+!> Initialise the console object
 subroutine console_init(console,plain_mode)
+    !> Console object to initialise
     class(console_t), intent(out), target :: console
+    !> 'Plain' output (no escape codes)
     logical, intent(in), optional :: plain_mode
 
     if (present(plain_mode)) then
@@ -41,10 +63,15 @@ subroutine console_init(console,plain_mode)
 
 end subroutine console_init
 
+!> Write a single line to the standard output
 subroutine console_write_line(console,str,line,advance)
+    !> Console object
     class(console_t), intent(inout), target :: console
+    !> String to write
     character(*), intent(in) :: str
+    !> Integer needed to later update console line
     integer, intent(out), optional :: line
+    !> Advancing output (print newline?)
     logical, intent(in), optional :: advance
 
     character(3) :: adv
@@ -72,9 +99,13 @@ subroutine console_write_line(console,str,line,advance)
 
 end subroutine console_write_line
 
+!> Overwrite a previously-written line in standard output
 subroutine console_update_line(console,line_no,str)
+    !> Console object
     class(console_t), intent(in) :: console
+    !> Integer output from `[[console_write_line]]`
     integer, intent(in) :: line_no
+    !> New string to overwrite line
     character(*), intent(in) :: str
 
     integer :: n

src/fpm_backend_output.f90

@@ -1,3 +1,14 @@
+!># Build Backend Progress Output
+!> This module provides a derived type `build_progress_t` for printing build status
+!> and progress messages to the console while the backend is building the package.
+!>
+!> The `build_progress_t` type supports two modes: `normal` and `plain`
+!> where the former does 'pretty' output and the latter does not.
+!> The `normal` mode is intended for typical interactive usage whereas
+!> 'plain' mode is used with the `--verbose` flag or when `stdout` is not attached
+!> to a terminal (e.g. when piping or redirecting `stdout`). In these cases,
+!> the pretty output must be suppressed to avoid control codes being output.
+
 module fpm_backend_output
 use iso_fortran_env, only: stdout=>output_unit
 use fpm_filesystem, only: basename
@@ -6,33 +17,43 @@ module fpm_backend_output
 use M_attr, only: attr, attr_mode
 implicit none
 
-type build_progress_t
+private
+public build_progress_t
 
+!> Build progress object
+type build_progress_t
+    !> Console object for updating console lines
     type(console_t) :: console
-
+    !> Number of completed targets
     integer :: n_complete
-    
+    !> Total number of targets scheduled
     integer :: n_target
-
+    !> 'Plain' output (no colors or updating)
     logical :: plain_mode = .true.
-
+    !> Store needed when updating previous console lines
     integer, allocatable :: output_lines(:)
-
+    !> Queue of scheduled build targets
     type(build_target_ptr), pointer :: target_queue(:)
-
 contains
+    !> Initialise build progress object
     procedure :: init => output_init
+    !> Output 'compiling' status for build target
     procedure :: compiling_status => output_status_compiling
+    !> Output 'complete' status for build target
     procedure :: completed_status => output_status_complete
+    !> Output finished status for whole package
     procedure :: success => output_progress_success
-
 end type build_progress_t
 
 contains
 
+    !> Initialise build progress object
     subroutine output_init(progress,target_queue,plain_mode)
+        !> Progress object to initialise
         class(build_progress_t), intent(out) :: progress
+        !> The queue of scheduled targets
         type(build_target_ptr), intent(in), target :: target_queue(:)
+        !> Enable 'plain' output for progress object
         logical, intent(in), optional :: plain_mode
 
         if (plain_mode) then
@@ -51,8 +72,11 @@ subroutine output_init(progress,target_queue,plain_mode)
 
     end subroutine output_init
 
+    !> Output 'compiling' status for build target and overall percentage progress
     subroutine output_status_compiling(progress, queue_index)
+        !> Progress object
         class(build_progress_t), intent(inout) :: progress
+        !> Index of build target in the target queue
         integer, intent(in) :: queue_index
 
         character(:), allocatable :: target_name
@@ -69,13 +93,13 @@ subroutine output_status_compiling(progress, queue_index)
 
             write(overall_progress,'(A,I4,A)') '[',100*progress%n_complete/progress%n_target,'%]'
 
-            if (progress%plain_mode) then
+            if (progress%plain_mode) then ! Plain output
 
                 !$omp critical
                 write(*,'(A8,A30)') trim(overall_progress),target_name
                 !$omp end critical
 
-            else
+            else ! Pretty output
 
                 write(output_string,'(A,T40,A,A)') target_name,attr('<yellow>compiling...</yellow>')
                 call progress%console%write_line(trim(output_string),progress%output_lines(queue_index))
@@ -88,10 +112,13 @@ subroutine output_status_compiling(progress, queue_index)
 
     end subroutine output_status_compiling
 
-
+    !> Output 'complete' status for build target and update overall percentage progress
     subroutine output_status_complete(progress, queue_index, build_stat)
+        !> Progress object
         class(build_progress_t), intent(inout) :: progress
+        !> Index of build target in the target queue
         integer, intent(in) :: queue_index
+        !> Build status flag
         integer, intent(in) :: build_stat
 
         character(:), allocatable :: target_name
@@ -118,13 +145,13 @@ subroutine output_status_complete(progress, queue_index, build_stat)
 
             write(overall_progress,'(A,I4,A)') '[',100*progress%n_complete/progress%n_target,'%] '
 
-            if (progress%plain_mode) then
+            if (progress%plain_mode) then  ! Plain output
 
                 !$omp critical
                 write(*,'(A8,A30,A7)') trim(overall_progress),target_name, 'done.'
                 !$omp end critical
 
-            else
+            else ! Pretty output
 
                 call progress%console%update_line(progress%output_lines(queue_index),trim(output_string))
 
@@ -136,14 +163,15 @@ subroutine output_status_complete(progress, queue_index, build_stat)
 
     end subroutine output_status_complete
 
+    !> Output finished status for whole package
     subroutine output_progress_success(progress)
         class(build_progress_t), intent(inout) :: progress
 
-        if (progress%plain_mode) then
+        if (progress%plain_mode) then ! Plain output
 
             write(*,'(A)') attr('<green>[100%] Project compiled successfully.</green>')
 
-        else
+        else ! Pretty output
 
             write(*,'(A)') progress%console%LINE_RESET//attr('<green>[100%] Project compiled successfully.</green>')
 

src/fpm_environment.f90

@@ -198,13 +198,6 @@ subroutine run(cmd,echo,exitstat,verbose,redirect)
                 end if
             end if
         end if
-        
-
-        if(present(redirect))then
-            verbose_local=verbose
-        else
-            verbose_local=.true.
-        end if
 
         if(echo_local) print *, '+ ', cmd
 

src/ptycheck/isatty.c

@@ -1,10 +1,17 @@
+// This file provides a `c_isatty` wrapper function to check if `stdout` is connected
+// to a terminal or not. This wrapper is required for better portability, specifically
+// for supporting the MS Windows command prompt and the MinTTY terminal used by MSYS2.
+
 #include <unistd.h>	//for isatty()
 #include <stdio.h>	//for fileno()
 
 #ifdef __MINGW64__
+// ptycheck/iscygpty allows us to check if connected to MinTTY in MSYS2 on Windows
 #include "iscygpty.h"
 #endif
 
+// Check if `stdout` is connected to a terminal
+// Returns 1 if is a terminal, and 0 otherwise
 int c_isatty(void)
 {