Pursuit of language-independent specification in current and future API's #14
Description
Looking in retrospect on #4, #5, #12, as far as I understand, the specification for Space API is supposed to be programming language-independent and paradigm-independent.
The naming structure in the specification of the operators seem to be methods and description of entities such as spaces, space repositories, etc. seem to be written in an OO oriented way.
I suggest that the specification contains a "Naming" section, and that this contains what naming scheme is used for the specification, and that the naming scheme should map appropriately to the naming scheme in an implementation language.
Similarly for the examples provided in the Space API: separating examples from the specification, and even providing examples for different languages paradigms in, say, an "Example" or "Examples in different paradigms" section.
Reason is that I see this can used to:
- Avoid misunderstanding when discussing and when using different language paradigms to explain the problem.
- Introducing of concepts that might be programming language specific into the specification.
- Starting discussions about actual implementation specific details as seen in e.g Discuss and describe the API related to repositories, spaces and gates #4 or Bounded spaces #12.
As discussed privately with @sequenze, the best thing to do is to describe behaviour and semantics of operations and entities one is working with and avoid any programming language specific details.
From that wouldn't it also make sense to make a "Definitions" section which lists clearly and unambiguously definitions of the different phrases that are used through the specification or would that be unnecessary?
@albertolluch @sequenze @michele-loreti @andreamargheri @mshPolo
Could this be achieved without necessarily doing a formal specification or is this not an issue?