Documentation improvement: Can Node be null?

[pjljvandelaar]

Dear LibAdaLang developers,

Libadalang is nicely documented.
For example, the function F_Suffix is documented in libadalang-analysis.adsas follows

   function F_Suffix
     (Node : Call_Expr'Class) return Ada_Node;
   --  This field can contain one of the following nodes:
   --  :ada:ref:`Attribute_Ref`, :ada:ref:`Basic_Assoc_List`,
   --  :ada:ref:`Bin_Op`, :ada:ref:`Call_Expr`, :ada:ref:`Char_Literal`,
   --  :ada:ref:`Discrete_Subtype_Indication`, :ada:ref:`Dotted_Name`,
   --  :ada:ref:`Explicit_Deref`, :ada:ref:`Identifier`, :ada:ref:`Qual_Expr`,
   --  :ada:ref:`Reduce_Attribute_Ref`, :ada:ref:`String_Literal`,
   --  :ada:ref:`Target_Name`, :ada:ref:`Update_Attribute_Ref`
   --% belongs-to: Call_Expr

Yet, I think there is room for improvement.

Suppose, I want to call Kind on the result of X.F_Suffix.
Kind requires that for its argument Y holds that Y.Is_Null returns false.

However, the documentation of F_Suffix states nothing about whether the node returned by F_Suffix can be null.
So, it is unclear whether a check like not X.F_Suffix.Is_Null is

• necessary before calling Kind or
• just hampering performance and wasting energy?

Can the documentation be extended with information about an Ada_Node being a nullnode?

Greetings,
Pierre

[pmderodat]

Hello @pjljvandelaar,

Because Libadalang may create a tree even in the presence of parsing errors, all node fields may be null. We’ll discuss if we’d want to augment these docstrings to specifically document the case of an error-free parsing.