Skip to content

Commit 6bb7cfc

Browse files
godunkogodunko
committed
Report undocumented entities and their components.
1 parent 59b9cf9 commit 6bb7cfc

File tree

5 files changed

+253
-0
lines changed

5 files changed

+253
-0
lines changed

‎source/frontend/gnatdoc-comments-undocumented_checker.adb‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
------------------------------------------------------------------------------
2+
-- GNAT Documentation Generation Tool --
3+
-- --
4+
-- Copyright (C) 2023, AdaCore --
5+
-- --
6+
-- This is free software; you can redistribute it and/or modify it under --
7+
-- terms of the GNU General Public License as published by the Free Soft- --
8+
-- ware Foundation; either version 3, or (at your option) any later ver- --
9+
-- sion. This software is distributed in the hope that it will be useful, --
10+
-- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHAN- --
11+
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
12+
-- License for more details. You should have received a copy of the GNU --
13+
-- General Public License distributed with this software; see file --
14+
-- COPYING3. If not, go to http://www.gnu.org/licenses for a complete copy --
15+
-- of the license. --
16+
------------------------------------------------------------------------------
17+
18+
with GNATdoc.Messages;
19+
20+
package body GNATdoc.Comments.Undocumented_Checker is
21+
22+
------------------------
23+
-- Check_Undocumented --
24+
------------------------
25+
26+
procedure Check_Undocumented
27+
(Location : GNATdoc.Entities.Entity_Location;
28+
Name : VSS.Strings.Virtual_String;
29+
Documentation : GNATdoc.Comments.Structured_Comment)
30+
is
31+
use type VSS.Strings.Virtual_String;
32+
33+
begin
34+
for Section of Documentation.Sections loop
35+
if Section.Kind in Description then
36+
if Section.Text.Is_Empty then
37+
GNATdoc.Messages.Report_Warning
38+
(Location, "entity " & Name & " is not documented");
39+
end if;
40+
41+
exit;
42+
end if;
43+
end loop;
44+
45+
for Section of Documentation.Sections loop
46+
if Section.Kind in Component
47+
and then Section.Text.Is_Empty
48+
then
49+
GNATdoc.Messages.Report_Warning
50+
(Location,
51+
VSS.Strings.To_Virtual_String
52+
(case Section.Kind is
53+
when Formal => "generic formal",
54+
when Enumeration_Literal => "enumeration literal",
55+
when Field => "component",
56+
when Parameter => "parameter",
57+
when Returns => "return value",
58+
when Raised_Exception => "raised exception",
59+
when others => raise Program_Error)
60+
& (if Section.Kind /= Returns
61+
then " " & Section.Name else "")
62+
& VSS.Strings.To_Virtual_String (" is not documented"));
63+
end if;
64+
end loop;
65+
end Check_Undocumented;
66+
67+
end GNATdoc.Comments.Undocumented_Checker;

‎source/frontend/gnatdoc-comments-undocumented_checker.ads‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
------------------------------------------------------------------------------
2+
-- GNAT Documentation Generation Tool --
3+
-- --
4+
-- Copyright (C) 2023, AdaCore --
5+
-- --
6+
-- This is free software; you can redistribute it and/or modify it under --
7+
-- terms of the GNU General Public License as published by the Free Soft- --
8+
-- ware Foundation; either version 3, or (at your option) any later ver- --
9+
-- sion. This software is distributed in the hope that it will be useful, --
10+
-- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHAN- --
11+
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
12+
-- License for more details. You should have received a copy of the GNU --
13+
-- General Public License distributed with this software; see file --
14+
-- COPYING3. If not, go to http://www.gnu.org/licenses for a complete copy --
15+
-- of the license. --
16+
------------------------------------------------------------------------------
17+
18+
with VSS.Strings;
19+
20+
with GNATdoc.Entities;
21+
22+
package GNATdoc.Comments.Undocumented_Checker is
23+
24+
procedure Check_Undocumented
25+
(Location : GNATdoc.Entities.Entity_Location;
26+
Name : VSS.Strings.Virtual_String;
27+
Documentation : GNATdoc.Comments.Structured_Comment);
28+
-- Check presense of the documentation for all components and report
29+
-- warnings when necessary.
30+
31+
end GNATdoc.Comments.Undocumented_Checker;

‎source/frontend/gnatdoc-frontend.adb‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ with Libadalang.Common;
2323
with VSS.Strings.Conversions;
2424

2525
with GNATdoc.Comments.Extractor;
26+
with GNATdoc.Comments.Undocumented_Checker;
27+
with GNATdoc.Configuration;
2628
with GNATdoc.Entities;
2729
with GNATdoc.Options;
2830

@@ -156,6 +158,24 @@ package body GNATdoc.Frontend is
156158
function Signature (Name : Defining_Name'Class) return Virtual_String;
157159
-- Computes unique signature of the given entity.
158160

161+
procedure Check_Undocumented
162+
(Entity : not null GNATdoc.Entities.Entity_Information_Access);
163+
-- Check whether entiry and all components of the entity are documented.
164+
-- Generate warnings when they are enabled.
165+
166+
------------------------
167+
-- Check_Undocumented --
168+
------------------------
169+
170+
procedure Check_Undocumented
171+
(Entity : not null GNATdoc.Entities.Entity_Information_Access) is
172+
begin
173+
if GNATdoc.Configuration.Provider.Warnings_Enabled then
174+
GNATdoc.Comments.Undocumented_Checker.Check_Undocumented
175+
(Entity.Location, Entity.Name, Entity.Documentation);
176+
end if;
177+
end Check_Undocumented;
178+
159179
--------------
160180
-- Location --
161181
--------------
@@ -194,6 +214,7 @@ package body GNATdoc.Frontend is
194214

195215
begin
196216
Enclosing.Access_Types.Insert (Entity);
217+
Check_Undocumented (Entity);
197218
end Process_Access_Type_Def;
198219

199220
----------------------------
@@ -216,6 +237,7 @@ package body GNATdoc.Frontend is
216237

217238
begin
218239
Enclosing.Array_Types.Insert (Entity);
240+
Check_Undocumented (Entity);
219241
end Process_Array_Type_Def;
220242

221243
----------------------------
@@ -243,6 +265,8 @@ package body GNATdoc.Frontend is
243265
if Global /= null and GNATdoc.Entities.Globals'Access /= Enclosing then
244266
Global.Subprograms.Insert (Entity);
245267
end if;
268+
269+
Check_Undocumented (Entity);
246270
end Process_Base_Subp_Body;
247271

248272
----------------------
@@ -548,6 +572,8 @@ package body GNATdoc.Frontend is
548572
if Global /= null and GNATdoc.Entities.Globals'Access /= Enclosing then
549573
Global.Subprograms.Insert (Entity);
550574
end if;
575+
576+
Check_Undocumented (Entity);
551577
end Process_Classic_Subp_Decl;
552578

553579
------------------------------
@@ -673,6 +699,8 @@ package body GNATdoc.Frontend is
673699
else
674700
Enclosing.Simple_Types.Insert (Entity);
675701
end if;
702+
703+
Check_Undocumented (Entity);
676704
end Process_Derived_Type_Def;
677705

678706
------------------------
@@ -695,6 +723,7 @@ package body GNATdoc.Frontend is
695723

696724
begin
697725
Enclosing.Entries.Insert (Entity);
726+
Check_Undocumented (Entity);
698727
end Process_Entry_Body;
699728

700729
------------------------
@@ -717,6 +746,7 @@ package body GNATdoc.Frontend is
717746

718747
begin
719748
Enclosing.Entries.Insert (Entity);
749+
Check_Undocumented (Entity);
720750
end Process_Entry_Decl;
721751

722752
----------------------------
@@ -743,6 +773,7 @@ package body GNATdoc.Frontend is
743773

744774
begin
745775
Enclosing.Exceptions.Insert (Entity);
776+
Check_Undocumented (Entity);
746777
end;
747778
end loop;
748779
end Process_Exception_Decl;
@@ -775,6 +806,8 @@ package body GNATdoc.Frontend is
775806
if Global /= null and GNATdoc.Entities.Globals'Access /= Enclosing then
776807
Global.Generic_Instantiations.Insert (Entity);
777808
end if;
809+
810+
Check_Undocumented (Entity);
778811
end Process_Generic_Instantiation;
779812

780813
----------------------------------
@@ -808,6 +841,8 @@ package body GNATdoc.Frontend is
808841
GNATdoc.Entities.Globals.Packages.Insert (Entity);
809842
end if;
810843

844+
Check_Undocumented (Entity);
845+
811846
Process_Children (Node.F_Package_Decl.F_Public_Part, Entity);
812847

813848
if GNATdoc.Options.Frontend_Options.Generate_Private then
@@ -835,6 +870,7 @@ package body GNATdoc.Frontend is
835870

836871
begin
837872
Enclosing.Interface_Types.Insert (Entity);
873+
Check_Undocumented (Entity);
838874
end Process_Interface_Type_Def;
839875

840876
-------------------------
@@ -861,6 +897,7 @@ package body GNATdoc.Frontend is
861897

862898
begin
863899
Enclosing.Constants.Insert (Entity);
900+
Check_Undocumented (Entity);
864901
end;
865902
end loop;
866903
end Process_Number_Decl;
@@ -894,6 +931,8 @@ package body GNATdoc.Frontend is
894931
else
895932
Enclosing.Variables.Insert (Entity);
896933
end if;
934+
935+
Check_Undocumented (Entity);
897936
end;
898937
end loop;
899938
end Process_Object_Decl;
@@ -929,6 +968,8 @@ package body GNATdoc.Frontend is
929968
GNATdoc.Entities.Globals.Packages.Insert (Entity);
930969
end if;
931970

971+
Check_Undocumented (Entity);
972+
932973
Process_Children (Node.F_Public_Part, Entity);
933974

934975
if GNATdoc.Options.Frontend_Options.Generate_Private then
@@ -972,6 +1013,8 @@ package body GNATdoc.Frontend is
9721013
GNATdoc.Entities.Globals.Packages.Insert (Entity);
9731014
end if;
9741015

1016+
Check_Undocumented (Entity);
1017+
9751018
Process_Children (Node.F_Decls, Entity);
9761019
end Process_Package_Body;
9771020

@@ -1001,6 +1044,8 @@ package body GNATdoc.Frontend is
10011044
if Global /= null and GNATdoc.Entities.Globals'Access /= Enclosing then
10021045
Global.Package_Renamings.Insert (Entity);
10031046
end if;
1047+
1048+
Check_Undocumented (Entity);
10041049
end Process_Package_Renaming_Decl;
10051050

10061051
------------------------------
@@ -1028,6 +1073,8 @@ package body GNATdoc.Frontend is
10281073
else
10291074
Enclosing.Simple_Types.Insert (Entity);
10301075
end if;
1076+
1077+
Check_Undocumented (Entity);
10311078
end Process_Private_Type_Def;
10321079

10331080
----------------------------
@@ -1059,6 +1106,8 @@ package body GNATdoc.Frontend is
10591106
GNATdoc.Entities.Globals.Packages.Insert (Entity);
10601107
end if;
10611108

1109+
Check_Undocumented (Entity);
1110+
10621111
Process_Children (Node.F_Decls, Entity);
10631112
end Process_Protected_Body;
10641113

@@ -1094,6 +1143,8 @@ package body GNATdoc.Frontend is
10941143
GNATdoc.Entities.Globals.Protected_Types.Insert (Entity);
10951144
end if;
10961145

1146+
Check_Undocumented (Entity);
1147+
10971148
Process_Children (Definition.F_Public_Part, Entity);
10981149

10991150
if GNATdoc.Options.Frontend_Options.Generate_Private then
@@ -1121,6 +1172,7 @@ package body GNATdoc.Frontend is
11211172

11221173
begin
11231174
Enclosing.Record_Types.Insert (Entity);
1175+
Check_Undocumented (Entity);
11241176
end Process_Record_Type_Def;
11251177

11261178
-----------------------------
@@ -1143,6 +1195,7 @@ package body GNATdoc.Frontend is
11431195

11441196
begin
11451197
Enclosing.Simple_Types.Insert (Entity);
1198+
Check_Undocumented (Entity);
11461199
end Process_Simple_Type_Def;
11471200

11481201
--------------------------
@@ -1165,6 +1218,7 @@ package body GNATdoc.Frontend is
11651218

11661219
begin
11671220
Enclosing.Subtypes.Insert (Entity);
1221+
Check_Undocumented (Entity);
11681222
end Process_Subtype_Decl;
11691223

11701224
-----------------------
@@ -1199,6 +1253,8 @@ package body GNATdoc.Frontend is
11991253
GNATdoc.Entities.Globals.Task_Types.Insert (Entity);
12001254
end if;
12011255

1256+
Check_Undocumented (Entity);
1257+
12021258
if not Decl.F_Definition.Is_Null then
12031259
Process_Children (Decl.F_Definition.F_Public_Part, Entity);
12041260

0 commit comments

Comments
 (0)