Skip to content

Commit b6b0e85

Browse files
godunkogodunko
committed
Merge branch 'topic/vadim/laldoc' into 'master'
Improve documentation generation by `rstpt` backend... See merge request eng/ide/gnatdoc!206
2 parents 4f8b01e + efca82c commit b6b0e85

18 files changed

+920
-65
lines changed

‎source/backend/rst/gnatdoc-backend-rst-pt.adb‎

Lines changed: 518 additions & 1 deletion
Large diffs are not rendered by default.

‎source/backend/rst/gnatdoc-backend-rst-pt.ads‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
------------------------------------------------------------------------------
22
-- GNAT Documentation Generation Tool --
33
-- --
4-
-- Copyright (C) 2023-2024, AdaCore --
4+
-- Copyright (C) 2023-2025, AdaCore --
55
-- --
66
-- This is free software; you can redistribute it and/or modify it under --
77
-- terms of the GNU General Public License as published by the Free Soft- --
@@ -23,13 +23,15 @@ package GNATdoc.Backend.RST.PT is
2323

2424
private
2525

26-
type PT_RST_Backend is new RST_Backend_Base (True) with null record;
26+
type PT_RST_Backend is new RST_Backend_Base with null record;
2727

2828
overriding function Name
2929
(Self : in out PT_RST_Backend) return VSS.Strings.Virtual_String;
3030

3131
overriding procedure Initialize (Self : in out PT_RST_Backend);
3232

33+
overriding procedure Generate (Self : in out PT_RST_Backend);
34+
3335
overriding procedure Add_Command_Line_Options
3436
(Self : PT_RST_Backend;
3537
Parser : in out VSS.Command_Line.Parsers.Command_Line_Parser'Class)

‎source/backend/rst/gnatdoc-backend-rst.adb‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,6 @@ with Streams;
2828

2929
package body GNATdoc.Backend.RST is
3030

31-
function Documentation_File_Name
32-
(Entity : Entity_Information) return VSS.Strings.Virtual_String;
33-
3431
procedure Generate_Documentation
3532
(Self : in out RST_Backend_Base'Class;
3633
Entity : Entity_Information);
@@ -158,7 +155,7 @@ package body GNATdoc.Backend.RST is
158155
File.Put (Indent, Success);
159156
File.Put (".. ada:object:: ", Success);
160157

161-
File.Put (Entity.RST_Profile, Success);
158+
File.Put (Entity.Name, Success);
162159
File.New_Line (Success);
163160
File.Put (Indent, Success);
164161
File.Put (" :package: ", Success);
@@ -170,7 +167,7 @@ package body GNATdoc.Backend.RST is
170167
(GNATdoc.Comments.RST_Helpers.Get_RST_Documentation
171168
(Indent => Indent & " ",
172169
Documentation => Entity.Documentation,
173-
Pass_Through => Self.Pass_Through,
170+
Pass_Through => False,
174171
Code_Snippet => False),
175172
Success);
176173
File.New_Line (Success);
@@ -216,7 +213,7 @@ package body GNATdoc.Backend.RST is
216213
(GNATdoc.Comments.RST_Helpers.Get_RST_Documentation
217214
(Indent => Indent & " ",
218215
Documentation => Entity.Documentation,
219-
Pass_Through => Self.Pass_Through,
216+
Pass_Through => False,
220217
Code_Snippet => False),
221218
Success);
222219
File.New_Line (Success);
@@ -241,7 +238,7 @@ package body GNATdoc.Backend.RST is
241238
(GNATdoc.Comments.RST_Helpers.Get_RST_Documentation
242239
(Indent => "",
243240
Documentation => Entity.Documentation,
244-
Pass_Through => Self.Pass_Through,
241+
Pass_Through => False,
245242
Code_Snippet => True),
246243
Success);
247244
File.New_Line (Success);
@@ -283,7 +280,7 @@ package body GNATdoc.Backend.RST is
283280
(GNATdoc.Comments.RST_Helpers.Get_RST_Documentation
284281
(Indent => " ",
285282
Documentation => Item.Documentation,
286-
Pass_Through => Self.Pass_Through,
283+
Pass_Through => False,
287284
Code_Snippet => True),
288285
Success);
289286

@@ -408,7 +405,7 @@ package body GNATdoc.Backend.RST is
408405
(GNATdoc.Comments.RST_Helpers.Get_RST_Documentation
409406
(Indent => " ",
410407
Documentation => Item.Documentation,
411-
Pass_Through => Self.Pass_Through,
408+
Pass_Through => False,
412409
Code_Snippet => True),
413410
Success);
414411

‎source/backend/rst/gnatdoc-backend-rst.ads‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ package GNATdoc.Backend.RST is
2121

2222
private
2323

24-
type RST_Backend_Base (Pass_Through : Boolean) is
24+
type RST_Backend_Base is
2525
abstract new Abstract_Backend with record
2626
OOP_Mode : Boolean := False;
2727
Alphabetical_Order : Boolean := True;
@@ -39,10 +39,15 @@ private
3939
(Self : in out RST_Backend_Base;
4040
Parser : VSS.Command_Line.Parsers.Command_Line_Parser'Class);
4141

42-
type RST_Backend is
43-
new RST_Backend_Base (False) with null record;
42+
type RST_Backend is new RST_Backend_Base with null record;
4443

4544
overriding function Name
4645
(Self : in out RST_Backend) return VSS.Strings.Virtual_String;
4746

47+
function Documentation_File_Name
48+
(Entity : GNATdoc.Entities.Entity_Information)
49+
return VSS.Strings.Virtual_String;
50+
-- Return name of the RST file to generate documentation for the given
51+
-- entity.
52+
4853
end GNATdoc.Backend.RST;

‎source/frontend/gnatdoc-entities.ads‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,13 @@ package GNATdoc.Entities is
2727
(Undefined,
2828
Ada_Tagged_Type,
2929
Ada_Interface_Type,
30+
Ada_Other_Type,
31+
Ada_Object,
32+
Ada_Exception,
3033
Ada_Function,
31-
Ada_Procedure);
34+
Ada_Procedure,
35+
Ada_Generic_Package_Instantiation,
36+
Ada_Generic_Subprogram_Instantiation);
3237

3338
type Entity_Signature is record
3439
Image : VSS.Strings.Virtual_String;
@@ -103,6 +108,12 @@ package GNATdoc.Entities is
103108

104109
RST_Profile : VSS.Strings.Virtual_String;
105110
-- Subprogram's profile in fortmat to use by RST backend
111+
RSTPT_Objtype : VSS.Strings.Virtual_String;
112+
-- Name of the type of the object
113+
RSTPT_Defval : VSS.Strings.Virtual_String;
114+
-- Default value of the object
115+
RSTPT_Instpkg : VSS.Strings.Virtual_String;
116+
-- Name of instantiated package
106117

107118
Packages : Entity_Information_Sets.Set;
108119
Subprograms : aliased Entity_Information_Sets.Set;

‎source/frontend/gnatdoc-frontend.adb‎

Lines changed: 88 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -721,7 +721,8 @@ package body GNATdoc.Frontend is
721721
Name : constant Defining_Name := Node.F_Name;
722722
Entity : constant not null GNATdoc.Entities.Entity_Information_Access :=
723723
new GNATdoc.Entities.Entity_Information'
724-
(Location => GNATdoc.Utilities.Location (Name),
724+
(Kind => GNATdoc.Entities.Ada_Other_Type,
725+
Location => GNATdoc.Utilities.Location (Name),
725726
Name => To_Virtual_String (Name.Text),
726727
Qualified_Name => To_Virtual_String (Name.P_Fully_Qualified_Name),
727728
Signature => Signature (Name),
@@ -748,7 +749,8 @@ package body GNATdoc.Frontend is
748749
Name : constant Defining_Name := Node.F_Name;
749750
Entity : constant not null GNATdoc.Entities.Entity_Information_Access :=
750751
new GNATdoc.Entities.Entity_Information'
751-
(Location => GNATdoc.Utilities.Location (Name),
752+
(Kind => GNATdoc.Entities.Ada_Other_Type,
753+
Location => GNATdoc.Utilities.Location (Name),
752754
Name => To_Virtual_String (Name.Text),
753755
Qualified_Name => To_Virtual_String (Name.P_Fully_Qualified_Name),
754756
Signature => Signature (Name),
@@ -1539,7 +1541,8 @@ package body GNATdoc.Frontend is
15391541
Entity : constant not null
15401542
GNATdoc.Entities.Entity_Information_Access :=
15411543
new GNATdoc.Entities.Entity_Information'
1542-
(Location => GNATdoc.Utilities.Location (Name),
1544+
(Kind => GNATdoc.Entities.Ada_Exception,
1545+
Location => GNATdoc.Utilities.Location (Name),
15431546
Name => To_Virtual_String (Name.Text),
15441547
Qualified_Name =>
15451548
To_Virtual_String (Name.P_Fully_Qualified_Name),
@@ -1573,7 +1576,14 @@ package body GNATdoc.Frontend is
15731576
else Node.As_Generic_Subp_Instantiation.F_Subp_Name);
15741577
Entity : constant not null GNATdoc.Entities.Entity_Information_Access :=
15751578
new GNATdoc.Entities.Entity_Information'
1576-
(Location => GNATdoc.Utilities.Location (Name),
1579+
(Kind =>
1580+
(case Node.Kind is
1581+
when Ada_Generic_Package_Instantiation =>
1582+
GNATdoc.Entities.Ada_Generic_Package_Instantiation,
1583+
when Ada_Generic_Subp_Instantiation =>
1584+
GNATdoc.Entities.Ada_Generic_Subprogram_Instantiation,
1585+
when others => raise Program_Error),
1586+
Location => GNATdoc.Utilities.Location (Name),
15771587
Name => To_Virtual_String (Name.Text),
15781588
Qualified_Name => To_Virtual_String (Name.P_Fully_Qualified_Name),
15791589
Signature => Signature (Name),
@@ -1591,6 +1601,10 @@ package body GNATdoc.Frontend is
15911601
Global.Generic_Instantiations.Insert (Entity);
15921602
end if;
15931603

1604+
Entity.RSTPT_Instpkg :=
1605+
VSS.Strings.To_Virtual_String
1606+
(Node.P_Designated_Generic_Decl.P_Fully_Qualified_Name);
1607+
15941608
Check_Undocumented (Entity);
15951609
end Process_Generic_Instantiation;
15961610

@@ -1768,22 +1782,56 @@ package body GNATdoc.Frontend is
17681782
(Node : Object_Decl'Class;
17691783
Enclosing : not null GNATdoc.Entities.Entity_Information_Access)
17701784
is
1785+
Objects_Parent : constant Basic_Decl := Node.P_Parent_Basic_Decl;
1786+
Type_Name : Defining_Name;
1787+
Type_Signature : GNATdoc.Entities.Entity_Signature;
1788+
Type_Parent : Basic_Decl;
1789+
1790+
RSTPT_Objtype : VSS.Strings.Virtual_String;
1791+
RSTPT_Defval : VSS.Strings.Virtual_String;
1792+
17711793
Template : constant VSS.Strings.Templates.Virtual_String_Template :=
17721794
"{} : constant {}";
17731795

17741796
begin
1797+
case Node.F_Type_Expr.Kind is
1798+
when Ada_Subtype_Indication =>
1799+
Type_Name :=
1800+
Node.F_Type_Expr.As_Subtype_Indication.P_Type_Name
1801+
.P_Referenced_Defining_Name;
1802+
Type_Signature := Signature (Type_Name);
1803+
Type_Parent := Type_Name.P_Parent_Basic_Decl.P_Parent_Basic_Decl;
1804+
1805+
RSTPT_Objtype :=
1806+
VSS.Strings.To_Virtual_String (Type_Name.P_Fully_Qualified_Name);
1807+
1808+
when Ada_Anonymous_Type =>
1809+
null;
1810+
1811+
when others =>
1812+
raise Program_Error;
1813+
end case;
1814+
1815+
if not Node.F_Default_Expr.Is_Null then
1816+
RSTPT_Defval :=
1817+
VSS.Strings.To_Virtual_String (Node.F_Default_Expr.Text);
1818+
end if;
1819+
17751820
for Name of Node.F_Ids loop
17761821
declare
1777-
Entity : constant not null
1822+
Entity : constant not null
17781823
GNATdoc.Entities.Entity_Information_Access :=
17791824
new GNATdoc.Entities.Entity_Information'
1780-
(Location => GNATdoc.Utilities.Location (Name),
1825+
(Kind => GNATdoc.Entities.Ada_Object,
1826+
Location => GNATdoc.Utilities.Location (Name),
17811827
Name => To_Virtual_String (Name.Text),
17821828
Qualified_Name =>
17831829
To_Virtual_String (Name.P_Fully_Qualified_Name),
17841830
Signature => Signature (Name),
1831+
RSTPT_Objtype => RSTPT_Objtype,
1832+
RSTPT_Defval => RSTPT_Defval,
17851833
others => <>);
1786-
Belongs : GNATdoc.Entities.Entity_Information_Access;
1834+
Belongs : GNATdoc.Entities.Entity_Information_Access;
17871835

17881836
begin
17891837
Extract
@@ -1801,6 +1849,30 @@ package body GNATdoc.Frontend is
18011849
Belongs => Belongs,
18021850
Entity => Entity);
18031851

1852+
-- If there is not explicitly defined @belongs-to tag, and
1853+
-- type is a "class", and both type and object are declared in
1854+
-- the same package, mark constant object as belongs to type.
1855+
1856+
if Belongs = null
1857+
and Node.F_Type_Expr.Kind = Ada_Subtype_Indication
1858+
then
1859+
1860+
if Type_Parent = Objects_Parent
1861+
and then GNATdoc.Entities.To_Entity.Contains
1862+
(Type_Signature)
1863+
and then GNATdoc.Entities.To_Entity (Type_Signature).Kind
1864+
in GNATdoc.Entities.Ada_Tagged_Type
1865+
| GNATdoc.Entities.Ada_Interface_Type
1866+
then
1867+
Belongs :=
1868+
GNATdoc.Entities.To_Entity (Signature (Type_Name));
1869+
end if;
1870+
1871+
Entity.RSTPT_Objtype :=
1872+
VSS.Strings.To_Virtual_String
1873+
(Type_Name.P_Fully_Qualified_Name);
1874+
end if;
1875+
18041876
if Belongs = null then
18051877
Enclosing.Belongs_Constants.Insert (Entity.Reference);
18061878

@@ -1956,7 +2028,8 @@ package body GNATdoc.Frontend is
19562028
Name : constant Defining_Name := Node.F_Name;
19572029
Entity : constant not null GNATdoc.Entities.Entity_Information_Access :=
19582030
new GNATdoc.Entities.Entity_Information'
1959-
(Location => GNATdoc.Utilities.Location (Name),
2031+
(Kind => GNATdoc.Entities.Ada_Other_Type,
2032+
Location => GNATdoc.Utilities.Location (Name),
19602033
Name => To_Virtual_String (Name.Text),
19612034
Qualified_Name => To_Virtual_String (Name.P_Fully_Qualified_Name),
19622035
Signature => Signature (Name),
@@ -2081,7 +2154,8 @@ package body GNATdoc.Frontend is
20812154
Name : constant Defining_Name := Node.F_Name;
20822155
Entity : constant not null GNATdoc.Entities.Entity_Information_Access :=
20832156
new GNATdoc.Entities.Entity_Information'
2084-
(Location => GNATdoc.Utilities.Location (Name),
2157+
(Kind => GNATdoc.Entities.Ada_Other_Type,
2158+
Location => GNATdoc.Utilities.Location (Name),
20852159
Name => To_Virtual_String (Name.Text),
20862160
Qualified_Name => To_Virtual_String (Name.P_Fully_Qualified_Name),
20872161
Signature => Signature (Name),
@@ -2096,6 +2170,7 @@ package body GNATdoc.Frontend is
20962170
GNATdoc.Entities.To_Entity.Insert (Entity.Signature, Entity);
20972171

20982172
if Node.F_Type_Def.As_Record_Type_Def.F_Has_Tagged then
2173+
Entity.Kind := GNATdoc.Entities.Ada_Tagged_Type;
20992174
Enclosing.Tagged_Types.Insert (Entity);
21002175
GNATdoc.Entities.Globals.Tagged_Types.Insert (Entity);
21012176

@@ -2117,7 +2192,8 @@ package body GNATdoc.Frontend is
21172192
Name : constant Defining_Name := Node.F_Name;
21182193
Entity : constant not null GNATdoc.Entities.Entity_Information_Access :=
21192194
new GNATdoc.Entities.Entity_Information'
2120-
(Location => GNATdoc.Utilities.Location (Name),
2195+
(Kind => GNATdoc.Entities.Ada_Other_Type,
2196+
Location => GNATdoc.Utilities.Location (Name),
21212197
Name => To_Virtual_String (Name.Text),
21222198
Qualified_Name => To_Virtual_String (Name.P_Fully_Qualified_Name),
21232199
Signature => Signature (Name),
@@ -2144,7 +2220,8 @@ package body GNATdoc.Frontend is
21442220
Name : constant Defining_Name := Node.F_Name;
21452221
Entity : constant not null GNATdoc.Entities.Entity_Information_Access :=
21462222
new GNATdoc.Entities.Entity_Information'
2147-
(Location => GNATdoc.Utilities.Location (Name),
2223+
(Kind => GNATdoc.Entities.Ada_Other_Type,
2224+
Location => GNATdoc.Utilities.Location (Name),
21482225
Name => To_Virtual_String (Name.Text),
21492226
Qualified_Name => To_Virtual_String (Name.P_Fully_Qualified_Name),
21502227
Signature => Signature (Name),

0 commit comments

Comments
 (0)