Old notes

except for 'control', which I would set to 'Upper'.

Some notes:

"methods": "dots" ( instead of "arrow", the old style )

a = object.MyMethod(b)

vs.

a = object->MyMethod(b)

The dot instead of the arrow is new (at least for me) and I was, at first, unsure and thought that the arrow indicates clearer that we want a method from a class and not a value from a structure. But the "dot" is much easier to write and in the context, it's clear whether we deal with a class/object or a structure. So I think we should go with the 'modern' format.

"control": "upper" ( instead of "lower" as is the default in the plugin )

FUNCTION test_format_func, input1, asdf = asdf
  COMPILE_OPT IDL2

  IF keyword_set(asdf) THEN help, input1

  result = 0
  FOR j = 0, n_elements(input1) - 1 DO BEGIN
    result += j
  ENDFOR

  return, result
END

vs.

function test_format_func, input1, asdf = asdf
  compile_opt idl2

  if keyword_set(asdf) then help, input1

  result = 0
  for j = 0, n_elements(input1) - 1 do begin
    result += j
  endfor

  return, result
end

This parameter governs the look of 'control' elements, such as PRO, FUNCTION, END, IF, FOR.
I think using uppercase letters for these elements makes the code more readable. Otherwise, we would have only lower letters and no upper letters in the whole code.

Conclusion

I think that we should use Visual Studio Code together with the IDL plugin so that we can make use of the auto-formatter and possibly the GitHub copilot plugin. Furthermore, Visual Studio Code seems to be a good and widely used editor.

Everyone should then enable format on save and use the same configuration.

The switch should be done in a separate git branch, with no other changes involved. The amount of work is not that huge, it consists mainly of opening and saving all files that should be formatted.

Auto documentation

The plugin also has the feature to auto-correct and -create the documentation.

https://interactive-data-language.github.io/vscode-idl/code-comments/auto_doc.html

This is by default disabled. And it can only be toggled on/off, there are no configuration parameters (yet?).

Pro

• All input arguments and keywords are automatically added to the documentation, with a generic text. I like this, so it's easy to see when a (new) input argument is not described in the document.
• The documentation is formatted in a (semi-)consistent way. Only semi because user-defined paragraphs are not ordered.
• In Visual Studio Code this formatting leads to better coloring of the documentation, thus better readability.
• VScode shows info about input arguments and keywords when hovering over them, also within the procedure.
• Might be a good idea to check the documentation anyway

Cons

• A lot of the solarsoft code already has a relatively consistent format for the documentation. But definitely not all of them.
• It would be quite A LOT OF WORK to integrate the current documentation into the new automatic one. Somebody would have to look at all the procedures and functions and make adjustments. I.e.
  • Copy content of arguments and keywords to proper place
  • Reformat the user defined paragraph
  • Order the user defined paragraph
  • Add missing descriptions of input
• The keywords and arguments are ordered alphabetically, this may affect the readability negatively. I.e. in spice_ingest the keywords were ordered into different paragraphs according to usage ('inputs', 'optional inputs', 'keywords', 'optional outputs'), see example below.

E.g. Documentation of spice_ingest

Now:

After AutoDoc:

These two documentations would have to be integrated by hand, and it would look something like this in the end:

Error message

'Unable to format code due to syntax error or problem in file'

• spice_fitshead2struct.pro
• spice_xcfit_block.pro
• spice_xcfit_block_old_ssw_version.pro