Skip to content

Commit 877b097

Browse files
author
automatic-merge
committed
Merge remote branch 'origin/master' into edge
2 parents ad7dab6 + 509e652 commit 877b097

File tree

13 files changed

+331
-41
lines changed

13 files changed

+331
-41
lines changed

‎examples/features/Makefile

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
2+
GNATDOC=gnatdoc
3+
#GNATDOC_FLAGS=--style=leading
4+
GNATDOC_FLAGS=--style=gnat
5+
6+
all: clean
7+
$(GNATDOC) $(GNATDOC_FLAGS) default.gpr
8+
$(GNATDOC) $(GNATDOC_FLAGS) default.gpr --backend=odf
9+
$(GNATDOC) $(GNATDOC_FLAGS) default.gpr --backend=rst
10+
11+
clean:
12+
rm -rf docs html odf

‎examples/features/default.gpr

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
2+
project Default is
3+
for Object_Dir use ".objs";
4+
5+
package Documentation is
6+
for Output_Dir ("html") use "html";
7+
for Image_Dirs ("html") use ("images");
8+
9+
for Output_Dir ("odf") use "odf";
10+
for Image_Dirs ("odf") use ("images");
11+
12+
for Output_Dir ("rst") use "rst";
13+
for Image_Dirs ("rst") use ("images");
14+
15+
-- for Output_Dir (others) use "docs";
16+
-- for Image_Dirs (others) use "images";
17+
-- `others` can be used to set attributes for all backends, but it is
18+
-- not supported by some tools yet.
19+
end Documentation;
20+
end Default;

‎examples/features/images/ada_logo_32x32.png

606 Bytes
Loading

‎examples/features/images/ada_logo_64x64.png

1.34 KB
Loading

‎examples/features/markdown.ads

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
2+
-- GNATdoc understands a markup language based on
3+
-- [CommonMark](https://commonmark.org/), which can be used to format
4+
-- elements in the generated documentation.
5+
--
6+
-- The following features are supported:
7+
-- * paragraphs
8+
-- * ordered and unordered lists
9+
-- * indented code blocks
10+
-- * inline formatting, including **strong emphasis** (**bold text**),
11+
-- *emphasis* (*italicized text*), and `code spans` (`monospace text`)
12+
-- * images
13+
--
14+
-- To have a block recognized as code, indent it with at least three spaces:
15+
--
16+
-- with Ada.Text_IO;
17+
--
18+
-- procedure Hello_World is
19+
-- begin
20+
-- Ada.Text_IO.Put_Line ("Hello, worlds!");
21+
-- end Hello_World;
22+
--
23+
-- Some backends require the size of images to be specified. When an image is
24+
-- declared without a size, the image might be invisible or shown with the
25+
-- wrong size, like this one ![Ada Inside](ada_logo_32x32.png). GNATdoc
26+
-- supports the following syntax to provide an image size. This guarantees
27+
-- this image will be represented properly on all backends
28+
-- ![Ada Inside](ada_logo_64x64.png){width=14pt height=14pt}.
29+
30+
package Markdown is
31+
32+
end Markdown;

‎examples/features/style_gnat_composite.ads

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
2+
-- GNATdoc supports two styles of locations for documentation comments
3+
-- * leading: the documentation comments are placed before entities
4+
-- * GNAT (trailing): the documentation comments are placed after the
5+
-- entities
6+
--
7+
-- In all styles, documentation comments must not be separated from the entity
8+
-- declaration by an empty line.
9+
--
10+
-- This package shows how comments should be written when the GNAT (trailing)
11+
-- style is used.
12+
--
13+
-- The documentation for composite entities should contain the documentation
14+
-- for the entity, and the documentation for elements composing the entity.
15+
--
16+
-- The documentation for an entity should have same indentation as the
17+
-- entity declaration. Any comments with deeper indentation are processed as
18+
-- documentation of elements composing the entity.
19+
--
20+
-- These elements can be documented in few ways:
21+
-- * a comment on the line of the element's identifier - in this case,
22+
-- comments on the following lines are considered as continuation of the
23+
-- documentation
24+
-- * a comment on the line immediately below the element's declaration, in
25+
-- which case comments on the following lines are considered as
26+
-- continuation of the documentation
27+
-- * using the corresponding GNATdoc tags in the documentation of the entity
28+
-- itself
29+
--
30+
-- All comments preceding a declaration are considered part of the documentation,
31+
-- stopping at the first blank or non-comment line.
32+
33+
package Style_GNAT_Composite is
34+
35+
type Enumeration_Type is
36+
(Item_1, -- Enumeration literal's description at the declaration line
37+
Item_2,
38+
-- Enumeration literal's description below declaration line
39+
Item_3);
40+
-- Enumeration type has description of the type and description of
41+
-- individual enumeration literals.
42+
--
43+
-- @enum Item_3 Enumeration literal's description using GNATdoc's tag in
44+
-- the documentation of the enumeration type.
45+
46+
type Record_Type is record
47+
Component_1 : Integer; -- Record component's description at the
48+
-- declaration line.
49+
Component_2 : Integer;
50+
-- Record component's description below the line of declaration.
51+
Component_3 : Integer;
52+
end record;
53+
-- Record type has description of the type and description of individual
54+
-- components.
55+
--
56+
-- @field Component_3 Record component's description using GNATdoc's tag in
57+
-- the documentation of the record type.
58+
59+
procedure Do_Something
60+
(X : Integer; -- Subprogram parameter's description at the line of
61+
-- declration.
62+
Y : Integer;
63+
-- Subprogram parameter's description below declaration line
64+
Z : Integer);
65+
-- All subprograms, including procedures, has description of the subprogram,
66+
-- description of parameters, and description of raised exceptions.
67+
--
68+
-- @param Z Subprogram parameter's description using GNATdoc's tag in the
69+
-- documentation of the subprogram.
70+
-- @exception Constraint_Error Description of conditions when an exception
71+
-- can be raised by the subprogram.
72+
73+
function Compute_Something_1 (X : Integer) return Integer;
74+
-- In addition to procedures, function has description of the return
75+
-- value.
76+
--
77+
-- @return Description of return value of the function with GNATdoc's tag.
78+
79+
function Compute_Something_2
80+
return Integer; -- Description of the return value at the line of
81+
-- `return`.
82+
-- Just another way to describe return value.
83+
84+
end Style_GNAT_Composite;

‎examples/features/style_leading_composite.ads

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
2+
-- GNATdoc supports two styles of locations for documentation comments
3+
-- * leading: the documentation comments are placed before entities
4+
-- * GNAT (trailing): the documentation comments are placed after the
5+
-- entities
6+
--
7+
-- In all styles, documentation comments must not be separated from the entity
8+
-- declaration by an empty line.
9+
--
10+
-- This package shows how comments should be written when the leading style
11+
-- is used.
12+
--
13+
-- The documentation for composite entities should contain the documentation
14+
-- for the entity, and the documentation for elements composing the entity.
15+
--
16+
-- The documentation for an entity should have same indentation as the
17+
-- entity declaration. Any comments with deeper indentation are processed as
18+
-- documentation of elements composing the entity.
19+
--
20+
-- These elements can be documented in few ways:
21+
-- * a comment on the line of the element's identifier
22+
-- * a comment on the line immediately below the element's declaration, in
23+
-- which case comments on the following lines are considered as
24+
-- continuation of the documentation
25+
-- * using the corresponding GNATdoc tags in the documentation of the entity
26+
-- itself
27+
--
28+
-- All comments preceding a declaration are considered part of the
29+
-- documentation, stopping at the first blank or non-comment line.
30+
31+
package Style_Leading_Composite is
32+
33+
-- Enumeration type has description of the type and description of
34+
-- individual enumeration literals.
35+
--
36+
-- @enum Item_3 Enumeration literal's description using GNATdoc's tag in
37+
-- the documentation of the enumeration type.
38+
type Enumeration_Type is
39+
(Item_1, -- Enumeration literal's description at the declaration line
40+
-- Enumeration literal's description below declaration line
41+
Item_2,
42+
Item_3);
43+
44+
-- Record type has description of the type and description of individual
45+
-- components.
46+
--
47+
-- @field Component_3 Record component's description using GNATdoc's tag in
48+
-- the documentation of the record type.
49+
type Record_Type is record
50+
Component_1 : Integer; -- Record component's description.
51+
-- Record component's description below the line of declaration.
52+
Component_2 : Integer;
53+
Component_3 : Integer;
54+
end record;
55+
56+
-- All subprograms, including procedures, has description of the subprogram,
57+
-- description of parameters, and description of raised exceptions.
58+
--
59+
-- @param Z Subprogram parameter's description using GNATdoc's tag in the
60+
-- documentation of the subprogram.
61+
-- @exception Constraint_Error Description of conditions when an exception
62+
-- can be raised by the subprogram.
63+
procedure Do_Something
64+
(X : Integer; -- Subprogram parameter's description at the line.
65+
-- Subprogram parameter's description below declaration line.
66+
Y : Integer;
67+
Z : Integer);
68+
69+
-- In addition to procedures, function has description of the return
70+
-- value.
71+
--
72+
-- @return Description of return value of the function with GNATdoc's tag.
73+
function Compute_Something_1 (X : Integer) return Integer;
74+
75+
-- Just another way to describe return value.
76+
function Compute_Something_2
77+
return Integer; -- Description of the return value at the line of return.
78+
79+
end Style_Leading_Composite;

‎share/gnatdoc/odf/template/documentation.fodt

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,15 @@
359359
<text:h tal:content='item/name' text:style-name="Heading_20_4" text:outline-level="4">Heading 4</text:h>
360360
<text:p tal:omit-tag='' tal:content='item/code_odf'>Entity declaration</text:p>
361361
<text:p tal:omit-tag='' tal:content='item/documentation/description_odf'>Entity description</text:p>
362+
<text:section tal:omit-tag='' tal:condition='item/documentation/enumeration_literals'>
363+
<text:list text:style-name="GNATdoc_20_component_20_list">
364+
<text:list-header><text:h text:style-name="GNATdoc_20_component_20_list_20_header" text:outline-level="5">Enumeration Literals</text:h></text:list-header>
365+
<text:list-item tal:repeat='literal item/documentation/enumeration_literals'>
366+
<text:h tal:content='literal/name' text:style-name="GNATdoc_20_component_20_list_20_item_20_header" text:outline-level="6">Name of the enumeration literal</text:h>
367+
<text:p tal:omit-tag='' tal:content='literal/description_odf'>Description of the enumeration literal</text:p>
368+
</text:list-item>
369+
</text:list>
370+
</text:section>
362371
</text:section>
363372

364373
<text:h tal:condition='entity/array_types' text:style-name="Heading_20_3" text:outline-level="3">Array Types</text:h>
@@ -373,6 +382,15 @@
373382
<text:h tal:content='item/name' text:style-name="Heading_20_4" text:outline-level="4">Heading 4</text:h>
374383
<text:p tal:omit-tag='' tal:content='item/code_odf'>Entity declaration</text:p>
375384
<text:p tal:omit-tag='' tal:content='item/documentation/description_odf'>Entity description</text:p>
385+
<text:section tal:omit-tag='' tal:condition='item/documentation/fields'>
386+
<text:list text:style-name="GNATdoc_20_component_20_list">
387+
<text:list-header><text:h text:style-name="GNATdoc_20_component_20_list_20_header" text:outline-level="5">Components</text:h></text:list-header>
388+
<text:list-item tal:repeat='field item/documentation/fields'>
389+
<text:h tal:content='field/name' text:style-name="GNATdoc_20_component_20_list_20_item_20_header" text:outline-level="6">Name of the component</text:h>
390+
<text:p tal:omit-tag='' tal:content='field/description_odf'>Description of the component</text:p>
391+
</text:list-item>
392+
</text:list>
393+
</text:section>
376394
</text:section>
377395

378396
<text:h tal:condition='entity/interface_types' text:style-name="Heading_20_3" text:outline-level="3">Interface Types</text:h>

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

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ package body GNATdoc.Backend.HTML_Markup is
4343
Text : VSS.Strings.Virtual_String);
4444

4545
overriding procedure Visit_Soft_Line_Break
46-
(Self : in out Annotated_Text_Builder) is null;
46+
(Self : in out Annotated_Text_Builder);
4747

4848
overriding procedure Enter_Emphasis
4949
(Self : in out Annotated_Text_Builder);
@@ -408,6 +408,18 @@ package body GNATdoc.Backend.HTML_Markup is
408408
Write_End_Element (Self.Stream, "em");
409409
end Leave_Emphasis;
410410

411+
---------------------------
412+
-- Visit_Soft_Line_Break --
413+
---------------------------
414+
415+
overriding procedure Visit_Soft_Line_Break
416+
(Self : in out Annotated_Text_Builder) is
417+
begin
418+
-- Convert soft line break into space character.
419+
420+
Self.Visit_Text (" ");
421+
end Visit_Soft_Line_Break;
422+
411423
----------------
412424
-- Visit_Text --
413425
----------------

‎source/backend/odf/gnatdoc-backend-odf_markup.adb

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ package body GNATdoc.Backend.ODF_Markup is
8181
Text : VSS.Strings.Virtual_String);
8282

8383
overriding procedure Visit_Soft_Line_Break
84-
(Self : in out Annotated_Text_Builder) is null;
84+
(Self : in out Annotated_Text_Builder);
8585

8686
overriding procedure Enter_Emphasis
8787
(Self : in out Annotated_Text_Builder);
@@ -607,6 +607,18 @@ package body GNATdoc.Backend.ODF_Markup is
607607
Write_End_Element (Self.Stream, Text_Namespace, "span");
608608
end Leave_Strong;
609609

610+
---------------------------
611+
-- Visit_Soft_Line_Break --
612+
---------------------------
613+
614+
overriding procedure Visit_Soft_Line_Break
615+
(Self : in out Annotated_Text_Builder) is
616+
begin
617+
-- Convert soft line break into space character.
618+
619+
Self.Visit_Text (" ");
620+
end Visit_Soft_Line_Break;
621+
610622
----------------
611623
-- Visit_Text --
612624
----------------

0 commit comments

Comments
 (0)