PLCgen naming / documenting strategy

PLCgen adopted the name strategy of cif2plc: Have a list of forbidden names. To create a new name, any candidate is checked against the list and modified until there is no clash any more. Then the new name is accepted, and added to the list to make it impossible to create the same name again.
This works in practice. It may lead to unexpected generated names though, which may make understanding the generated PLC code more difficult. Cif2Plc therefore can emit a warning for renamed variables to warn the user about it, and this idea has been adopted in PLCgen as well.

There are however also a few disadvantages to this approach:

• Creating a complete list of forbidden names is non-trivial without deep knowledge about a PLC system. It's not just the language keywords (in all its languages), but also all its functions (including type-extensions), all function block types, and all names in all extensions that may get added.
• In emitting rename warnings, PLCgen makes a choice what variables are "close enough" to be reported. This may not be sufficient. For example, the generated code has a variable to store the selected edge of an automaton to use in a transition.
  • Is such a variable easy to grasp for a CIF user? Probably not.
  • Is the variable relevant for grasping how the generated code works? Definitely!
• For a review of generated PLC code, it seems useful to have a general description of the code structure, and a description how that general structure maps to code blocks and key variables at PLC level (rather than CIF user level that we have with the warnings currently). The general code structure can probably be described in a document, the mapping however should be generated, since the details are different for each case.

Therefore, maybe the naming strategy and naming reporting should be somewhat changed. I propose the following:

• Drop the idea of a forbidden list, too complicated to get 100% coverage. Instead, always use the same suffix not used by the PLC system to distinguish between "system" names and generated names. My first thought was _ but that is not very visible, and may not be acceptable to a PLC system. Other options are eg _x, _gen, or _cif. This cleanly splits the namespace in two clearly distinct sets.

  • This eliminates any chance of getting conflicting names. No need to make a list of forbidden names any more.

• Generate comments to explain the code:

  • Assume knowledge about requirements, automata, locations, edges, and event transitions (without that nothing will make sense I think).
  • For each key variable, explain it's role. I am currently thinking mostly one-line sentences, e.g. "Automaton xyz:\n Edge selection variable 'abc'". Key variables here are perhaps everything until you reach the point of evaluating predicates?
  • Explain assigned values for some variables. E.g. edge variable values are non-trivial to decipher. Currently that is the case because they truly are magic numbers. However, even if you improve that, pointing at an edge in a location in an automaton is non-trivial as edges don't have unique names. It thus needs a numbering system that is logical and predictable.
  • This makes the warning message obsolete.
    Anyone interested in name mappings used in the generated code is looking at the generated code already, and doesn't need the warning text since there are comments explaining them.

Addresses #679

Transition names (and numbers) strategy

It seems the following is useful for enhancing transition computing code with respect to CIF names and values used there.

• Explain how CIF derives transitions in PLC-engineer terms. Not so much how to concretely do it, but more as a global overview of the steps involved, and how the steps relate to each other. Also mention some key concepts like automaton, location, and edge. In that way, a reference frame exists for mapping actual computations into the overall picture. (!878 (merged))
• Magic numbers enhancement. Magic numbers can be avoided but cannot eliminated, as PLC systems may support neither enumerations nor constants.
  • Introduce magic number triplets encoded as 12_345_67 integers. Magic triplet values have consistent meaning throughout the code and it improves on expressing how numbers are related to each other.
  • Document the numbers by linking them back to CIF names. The form is a bit of a question, may need some experimenting. Current options
    • Document all numbers in one comment block.
    • Document the used magic values near the code that does the computation.
    • Both
  • Explain how triplet magic numbers are derived and how they relate to each other.
• For systems that support constants, the magic numbers can be hidden behind names of constants. May need explaining how magic names relate to each other.
• For systems that support enumerations, the magic numbers can be replaced by enumeration literals. May need explaining how magic names relate to each other.

Note that currently, a generated PLC program does not include the CIF input text. As such, linking back to CIF text may be of limited value in some cases.

Addresses #679