Merge branch 'topic/vadim/example' into 'master'

Features example

See merge request eng/ide/gnatdoc!182

Author: godunko

examples/features/Makefile

@@ -0,0 +1,12 @@
+
+GNATDOC=gnatdoc
+#GNATDOC_FLAGS=--style=leading
+GNATDOC_FLAGS=--style=gnat
+
+all: clean
+	$(GNATDOC) $(GNATDOC_FLAGS) default.gpr
+	$(GNATDOC) $(GNATDOC_FLAGS) default.gpr --backend=odf
+	$(GNATDOC) $(GNATDOC_FLAGS) default.gpr --backend=rst
+
+clean:
+	rm -rf docs html odf

examples/features/default.gpr

@@ -0,0 +1,20 @@
+
+project Default is
+   for Object_Dir use ".objs";
+
+   package Documentation is
+      for Output_Dir ("html") use "html";
+      for Image_Dirs ("html") use ("images");
+
+      for Output_Dir ("odf") use "odf";
+      for Image_Dirs ("odf") use ("images");
+
+      for Output_Dir ("rst") use "rst";
+      for Image_Dirs ("rst") use ("images");
+
+      --  for Output_Dir (others) use "docs";
+      --  for Image_Dirs (others) use "images";
+      --  `others` can be used to set attributes for all backends, but it is
+      --  not supported by some tools yet.
+   end Documentation;
+end Default;

examples/features/images/ada_logo_32x32.png

@@ -0,0 +1,32 @@
+
+--  GNATdoc understands a markup language based on
+--  [CommonMark](https://commonmark.org/), which can be used to format
+--  elements in the generated documentation.
+--
+--  The following features are supported:
+--   * paragraphs
+--   * ordered and unordered lists
+--   * indented code blocks
+--   * inline formatting, including **strong emphasis** (**bold text**),
+--     *emphasis* (*italicized text*), and `code spans` (`monospace text`)
+--   * images
+--
+--  To have a block recognized as code, indent it with at least three spaces:
+--
+--     with Ada.Text_IO;
+--
+--     procedure Hello_World is
+--     begin
+--        Ada.Text_IO.Put_Line ("Hello, worlds!");
+--     end Hello_World;
+--
+--  Some backends require the size of images to be specified. When an image is
+--  declared without a size, the image might be invisible or shown with the
+--  wrong size, like this one ![Ada Inside](ada_logo_32x32.png). GNATdoc
+--  supports the following syntax to provide an image size. This guarantees
+--  this image will be represented properly on all backends
+--  ![Ada Inside](ada_logo_64x64.png){width=14pt height=14pt}.
+
+package Markdown is
+
+end Markdown;

examples/features/images/ada_logo_64x64.png

@@ -0,0 +1,84 @@
+
+--  GNATdoc supports two styles of locations for documentation comments
+--   * leading: the documentation comments are placed before entities
+--   * GNAT (trailing): the documentation comments are placed after the
+--     entities
+--
+--  In all styles, documentation comments must not be separated from the entity
+--  declaration by an empty line.
+--
+--  This package shows how comments should be written when the GNAT (trailing)
+--  style is used.
+--
+--  The documentation for composite entities should contain the documentation
+--  for the entity, and the documentation for elements composing the entity.
+--
+--  The documentation for an entity should have same indentation as the
+--  entity declaration. Any comments with deeper indentation are processed as
+--  documentation of elements composing the entity.
+--
+--  These elements can be documented in few ways:
+--   * a comment on the line of the element's identifier - in this case,
+--     comments on the following lines are considered as continuation of the
+--     documentation
+--   * a comment on the line immediately below the element's declaration, in
+--     which case comments on the following lines are considered as
+--     continuation of the documentation
+--   * using the corresponding GNATdoc tags in the documentation of the entity
+--     itself
+--
+--  All comments preceding a declaration are considered part of the documentation,
+--  stopping at the first blank or non-comment line.
+
+package Style_GNAT_Composite is
+
+   type Enumeration_Type is
+     (Item_1,  --  Enumeration literal's description at the declaration line
+      Item_2,
+      --  Enumeration literal's description below declaration line
+      Item_3);
+   --  Enumeration type has description of the type and description of
+   --  individual enumeration literals.
+   --
+   --  @enum Item_3 Enumeration literal's description using GNATdoc's tag in
+   --  the documentation of the enumeration type.
+
+   type Record_Type is record
+      Component_1 : Integer;  --  Record component's description at the
+                              --  declaration line.
+      Component_2 : Integer;
+      --  Record component's description below the line of declaration.
+      Component_3 : Integer;
+   end record;
+   --  Record type has description of the type and description of individual
+   --  components.
+   --
+   --  @field Component_3 Record component's description using GNATdoc's tag in
+   --  the documentation of the record type.
+
+   procedure Do_Something
+     (X : Integer;  --  Subprogram parameter's description at the line of
+                    --  declration.
+      Y : Integer;
+      --  Subprogram parameter's description below declaration line
+      Z : Integer);
+   --  All subprograms, including procedures, has description of the subprogram,
+   --  description of parameters, and description of raised exceptions.
+   --
+   --  @param Z Subprogram parameter's description using GNATdoc's tag in the
+   --  documentation of the subprogram.
+   --  @exception Constraint_Error Description of conditions when an exception
+   --  can be raised by the subprogram.
+
+   function Compute_Something_1 (X : Integer) return Integer;
+   --  In addition to procedures, function has description of the return
+   --  value.
+   --
+   --  @return Description of return value of the function with GNATdoc's tag.
+
+   function Compute_Something_2
+     return Integer;  --  Description of the return value at the line of
+                      --  `return`.
+   --  Just another way to describe return value.
+
+end Style_GNAT_Composite;

examples/features/markdown.ads

@@ -0,0 +1,79 @@
+
+--  GNATdoc supports two styles of locations for documentation comments
+--   * leading: the documentation comments are placed before entities
+--   * GNAT (trailing): the documentation comments are placed after the
+--     entities
+--
+--  In all styles, documentation comments must not be separated from the entity
+--  declaration by an empty line.
+--
+--  This package shows how comments should be written when the leading style
+--  is used.
+--
+--  The documentation for composite entities should contain the documentation
+--  for the entity, and the documentation for elements composing the entity.
+--
+--  The documentation for an entity should have same indentation as the
+--  entity declaration. Any comments with deeper indentation are processed as
+--  documentation of elements composing the entity.
+--
+--  These elements can be documented in few ways:
+--   * a comment on the line of the element's identifier
+--   * a comment on the line immediately below the element's declaration, in
+--     which case comments on the following lines are considered as
+--     continuation of the documentation
+--   * using the corresponding GNATdoc tags in the documentation of the entity
+--     itself
+--
+--  All comments preceding a declaration are considered part of the
+--  documentation, stopping at the first blank or non-comment line.
+
+package Style_Leading_Composite is
+
+   --  Enumeration type has description of the type and description of
+   --  individual enumeration literals.
+   --
+   --  @enum Item_3 Enumeration literal's description using GNATdoc's tag in
+   --  the documentation of the enumeration type.
+   type Enumeration_Type is
+     (Item_1,  --  Enumeration literal's description at the declaration line
+      --  Enumeration literal's description below declaration line
+      Item_2,
+      Item_3);
+
+   --  Record type has description of the type and description of individual
+   --  components.
+   --
+   --  @field Component_3 Record component's description using GNATdoc's tag in
+   --  the documentation of the record type.
+   type Record_Type is record
+      Component_1 : Integer;  --  Record component's description.
+      --  Record component's description below the line of declaration.
+      Component_2 : Integer;
+      Component_3 : Integer;
+   end record;
+
+   --  All subprograms, including procedures, has description of the subprogram,
+   --  description of parameters, and description of raised exceptions.
+   --
+   --  @param Z Subprogram parameter's description using GNATdoc's tag in the
+   --  documentation of the subprogram.
+   --  @exception Constraint_Error Description of conditions when an exception
+   --  can be raised by the subprogram.
+   procedure Do_Something
+     (X : Integer;  --  Subprogram parameter's description at the line.
+      --  Subprogram parameter's description below declaration line.
+      Y : Integer;
+      Z : Integer);
+
+   --  In addition to procedures, function has description of the return
+   --  value.
+   --
+   --  @return Description of return value of the function with GNATdoc's tag.
+   function Compute_Something_1 (X : Integer) return Integer;
+
+   --  Just another way to describe return value.
+   function Compute_Something_2
+     return Integer;  --  Description of the return value at the line of return.
+
+end Style_Leading_Composite;