AdaCore/libadalang

Improve documentation

pjljvandelaar opened this issue · 2 comments

pjljvandelaar commented

During a meeting with AdaCore, Nexperia and ESI, we were asked by AdaCore to submit this issue.

Improved Documentation

Could the technical documentation of libadalang be improved?
For example, by adopting GNATdoc and enforcing that each and every function/parameter is described.

For illustration purposes, I have a lot of difficulties in understanding the following code (line 2487-2492 of libadalang-analysis.ads):

   function P_Find_All_In
     (Node   : Ada_Node'Class; Root : Ada_Node'Class; Mode : Find_All_Mode;
      Origin : Ada_Node'Class; Imprecise_Fallback : Boolean := False)
      return Ada_Node_Array;
   --  Searches all references to this defining name in the given node and its
   --  children.

Please

  • improve the overal description of this function.
  • answer why is there no input of type Defining_Name while the documentation mentions this defining name?
  • describe all three given nodes : Node, Root and Origin! The text currently only mentions two nodes this defining name and the given node.
raph-amiard commented

Hello @pjljvandelaar ,

Since you're a supported user, you should open such issues via your customer account.

Thanks in advance. Closing this issue.

pjljvandelaar commented

I consider having multiple issues list for a single open source tool confusing.
Yet, I will follow your instructions.