Fix issue 372 - Sorting help text

[teddychao]

Fixes #372.

1 Abstract

Background Help text, which are shown as the top several lines of comments, are used to improve readability for users and our following software improvement.
Motivations (a) Currently the help text lacks maintenance and some of that is incomplete. (b) The help text in the source code of functions and the text in the GUI are also saved separately, which leads to confusion when there are differences between them. (c) Another pull request 385 aims at provide an excel file showing the subfields of options for each function, but some functions have incomplete help text. Therefore, this pull request is required for completing pull request 385.
Objective The pull request aims to sort out help text into several modules for further development.
Results Now the help text has been sorted out into some modules (listed below). A helper function has been added to link the help text and the GUI text. An excel file has been added to demonstrate the progress of help text sorting.
Future Work Future sorting for the functions which are marked as incomplete in the excel file is required.

2 Code Sorting Rule

Currently, the help text includes several modules as shown below

• Description
  • Description is encouraged to be written as one sentence which precisely demonstrate the use of the function. Details and explanations of the function should be moved to the following relevant modules.
• Format
  • Format shows how the function can be called and how arguments and outputs are sorted. Some functions contain varargins, in this case different kinds of argument calling should be listed so that users can understand how to call it.
• Arguments
  • Arguments shows the details of each input variable for the function. For each variable, the following information should be provided as explicit as possible, which is supportive for further code development and user's guide.
    • name
    • meaning
    • type, e.g. double / character / cell array / vector / matrix etc.
    • necessity, e.g. mandatory or optional
    • default value
    • acceptable value(s)
    • subfields if it is a struct or a subfield of a struct which further contains sub-subfields
• Outputs
  • Outputs demonstrates the variables as the outputs of the function by giving explicit explanations for them.
• Developer's Notes
  • All the content that is essential for understanding the function but too detailed to be put in Description should be put in Developer's Notes.
  • Some notes by developers, for example the current function lacks some features that are to be added in the future, should be put here as well.
• References
  • The paper that is encouraged to be cited if the function is used for data analysis in some users' work, is added here.
  • The citation is encouraged to be written in APA 7th format, available from PubMed.
• Introduced In
  • Introduced In includes the version number of PsPM when the function was firstly added to PsPM.
• Written By
  • Written By includes the author(s) who initially contributed to function development and the author(s) who significantly contribute to the function by adding new features.
• Maintained By
  • Maintained By includes the author(s) who provided minor improvement but not significant functional contribution to the functions, which could be either the help text / comment / annotations or bug fixes.

3 Linking GUI and Help Text

A helper, which can load help text from scripts and show them at somewhere users want to see, has been added in this pull request, which is pspm_help. However, pspm_help has not been implemented to many functions, currently only to pspm_cfg_import. Further work is required for implementing pspm_help to other functions.

As shown in Figure 1, pspm_help can now recognise the help text that can be delivered to the GUI or the developer's guide.

Figure 1 Example showing how help text is recognised and delivered to the GUI

An example of reading the help text from source code to the GUI is shown here. The action of reading help text is an automatic process.

Figure 2 Example showing the provided help text from the function's source code to the GUI

4 Progress of Help Text Sorting

The progress of sorting help text is summarised in the excel file: PsPM-help_text_progress.xlsx under the folder doc, as is shown in Figure 3.

Figure 3 Table showing the progress of help text sorting

Legend
✅ The module has been written completely according to the maintainer.
❌ The module has not been added.
🚫 The module is not required for the function.
❓ The module has been partly written but helps are need to complete it.

5 Case studies

The following screen shots

5.1 pspm_bf_FIR

Figure 4 pspm_bf_FIR, help text displayed in MATLAB

5.2 pspm_dcm_inv

Figure 5 pspm_dcm_inv, help text displayed in MATLAB, part A
:--:
Figure 6 pspm_dcm_inv, help text displayed in MATLAB, part B

[jbrochar]

It is a lot of work congratulation!
It seems to me that it was mostly about reformatting and simplifying some warning messages right? (for instance in pspm_con2).
If it was not the case then I may have missed it, even though I checked everything.