Documentation as part of the Ada Language Standard

[pjljvandelaar]

During a meeting with AdaCore, Nexperia and ESI, we were asked by AdaCore to submit this issue to trigger a discussion to determine whether a RFC is justified.

Documentation as part of the Ada Language Standard

Understandability is key

• Code is more often read than written by humans.
• Documentation is as important for human understanding as the Ada code
• Documentation should be treated as a first class citizen, just as Pre and Post conditions
• We would like our source code to be the single source of truth, so documentation should be integrated with the code as much as possible.

Standardization

Not only standardize the programming language Ada but also

• Integrated documentation,
• Pre-conditions, post-conditions, invariants,
• Examples, Test cases, Properties
• ...

Furthermore, enable checking by tools, e.g. warning when function is NOT documented.

Current Situation

Now de facto standards exist, such as AdaDoc and GNATdoc. However,

• Documentation is hidden in comment, and NOT an aspect like Pre and Post conditions
• Refactoring tooling can ignore documentation since it is NOT official part of the language. This hampers both productivity and adoption of refactoring tooling.
• The de facto standards differ not only among each other, but also with other programming languages. Many developers have prior experience with other languages before learning Ada. See e.g. javadoc and Doxygen. Please keep the adoption of Ada as simple as possible.
• tools differ in their implementation. E.g. GPS and GNATStudio treat GNATDoc differently in specific cases.

Features

The documentation should support the following features

• Documentation of declarations and their parameters.
• Support for references to language elements, such as functions and packages.
• Support for figures. Specification of state machines, UML, and SysML. (Via PlantUML or graphviz/dot)
• Control over elements in automatically generated figures, like call-graphs, to prevent too large and unreadable graphs when all elements are included. Examples of control include the selection based on kind, depth, and scope (file, package, set of packages).

[raph-amiard]

Thanks a lot for opening this issue. First, I agree that this is an under specified aspect in the Ada world. Thanks for participating your requirements.

We'll study that in more detail and give some feedback here.

[mhatzl]

A quick look over AdaDoc and GNATdoc and the returned format for AdaDoc (HTML, Latex, StrongHelp) and GNATdoc (HTML) seem a bit limiting. As markdown is becoming more and more a standard for online platforms, I would recommend markdown like documentation in code that is then generated into markdown files.

For the most feature rich markdown syntax I suggest pandoc markdown. With the help of pandoc you can then very easily convert your documentation to a lot of different formats.

[dhombios]

ARG recently created a repo and a website for proposing new AIs. As this suggestion is related to the Ada standard, it might be worth also adding it to that repo.

I also think that documentation could be worth including in the standard, specially for documenting mathematical models used in the program (equations can be difficult to read in comments and code, so markdown can be quite useful to help the reader understand the program behavior, like Jupyter notebooks do)

[pjljvandelaar]

Recently, we noticed another advance of treating documentation like aspects: making clear to which element documentation applies. Currently, it is up to the reader to determine whether documentation in a comment belongs to either the statement before or after that comment. Unfortunately, this is not always straightforward!