AUTODOC.txt

                              ТЕХНИЧЕСКОЕ ЗАДАНИЕ

                           Алгоритм  автоматического
                       составления документации к модулю
                       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Поставляемая с компилятором программа для автоматического создания
документации к проекту работает с исходным кодом модулей проекта и
предполагает специальное оформление комментариев в исходном коде.

Комментарии, попадающие в документацию будем называть спецкомментариями.
Спецкомментарии начинаются со скобки, за которой идёт ровно две звёздочки:

    Пример:
            CONST strLen = 256;  (** Это пойдёт в документацию *)

Система производит частичный синтаксический анализ исходного кода модуля и
улавливает находяющуюся в нём информацию об экспортированных объектах, а также
спецкомментарии к ним. Полученные данные сохраняются в древовдиной динамической
структуре данных. Эта структура данных затем может использоваться для вывода
документации к модулю в виде текста, двоичном виде или в формате HTML.

Для примера будет использован модуль Apples, текст которого приведён ниже:

(** Module Apples helps count apples.
    One can create a variable of type Apples.Apple,
    call Init and other procedures on it. *)
MODULE Apples;
(** Это тестовый модуль. *)
IMPORT Out, Fruits;

CONST
  (** Общие постоянные **)
  maxApples*  =  5; (** Maximum amount of apples. Currently unused *)
  maxSeeds*   = 10; (** Currently not in use *)
  startApples =  0; (** Start amount of apples. Used in Reset *)

  (** Качество яблока **)
  unknown* = 0; (** Неизвестное качество *)
  good*    = 1; (** Сносное качество *)
  bad*     = 2; (** Отвратное качество *)

TYPE
  (** Тип яблоко *)
  Apple* = RECORD(Fruits.Fruit) (** Represents an apple with some seeds *)
    seeds*: INTEGER;   (** Amount of seeds in the apple *)
    quality*: INTEGER; (** Качество продукта, см. @Качество яблока *)
    added: BOOLEAN     (** Whether Add was called on this seed after Init *)
  END;

VAR
  applesCreated*: INTEGER; (** How many apples were created using Init *)
  (** If FALSE, Show shows a welcome message and sets shown to TRUE *)
  shown: BOOLEAN;
  lastAdded*: INTEGER; (** How many seeds were added the last time, or -1 *)

(** Sets the given amount of seeds to apple a. *)
PROCEDURE Set(VAR a: Apple; seeds: INTEGER);
BEGIN
  a.seeds := seeds;
  IF seeds >= 3 THEN a.quality := good
  ELSIF seeds = 0 THEN a.quality := bad
  ELSE a.quality := unknown
  END
END Set;

PROCEDURE Init*(VAR a: Apple; seeds: INTEGER);
(** Initializes apple a with the specified amount of seeds. *)
BEGIN
  INC(applesCreated);
  Set(a, seeds);
  a.added := FALSE
END Init;

(** Apple manipulation **)

(** Adds n seeds to apple a. *)
PROCEDURE Add*(VAR a: Apple; n: INTEGER);
BEGIN
  lastAdded := n;
  Set(a, a.seeds + n);
  a.added := TRUE
END Add;

PROCEDURE Show*(a: Apple);
(** Dispalys a message about the apple. *)
BEGIN
  IF ~shown THEN
    Out.String('Welcome to Apples!');
    Out.Ln;
    shown := TRUE
  END;
  IF a.added THEN
    Out.String('Added apple with ')
  ELSE
    Out.String('Apple with ')
  END;
  Out.Int(a.seeds, 0);
  Out.String(' seeds.');
  Out.Ln
END Show;

(** - **)

(** Resets internal apple counter. *)
PROCEDURE Reset*;
BEGIN
  lastAdded := -1;
  applesCreated := startApples;
  shown := FALSE
END Reset;

PROCEDURE Shown*(): BOOLEAN; RETURN shown END Shown; (** Было ли приветствие *)

BEGIN
  Reset
END Apples.

                   Принципы работы алгоритма автоматического
                       составления документации к модулю
                       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Учитываются только экспортированные объекты.

2. Модуль учитыватеся в любом случае.

3. Учитываются только комментарии с двумя звёздочками в начале (** ... *)

4. Если комментарий имеет две звёздочки в конце (** ... **), это запоминается.

5. Есть 7 типов объектов:
   модуль (он один), константы, типы, переменные, процедуры, параметры,
   переменные. К последним относятся также и поля записей.

6. Пробельные литеры между словами комментария замещаются единичным пробелом.
   (**     Hello   world
       Comment  *)        ---> 'Hello world Comment'

7. Если среди пробельных литер есть два переноса строки, выполняется перенос.
   (**     Hello   world

       Comment  *)        ---> 'Hello world[0AX]Comment'

8. Если строчки комментария имеют больший отступ, чем та величина, на которую
   отстоит от начала строки первая буква комментария, то эти пробелы лишние
   сохраняются, а вместе с ними и переносы до и после указанных строк.
   (** This is my   comment             (** This is my   comment
       With a normal   indent. *)        Also with a normal   indent. *)

              ---> 'This is my comment With a normal indent.'

   (** This is my   comment
         With a bigger   indent.
       And a normal   continuation. *)   --->

   'This is my comment[0AX]' +
   '  With a bigger   indent.[0AX]' +
   'And a normal continuation.'

9. Все комментарии, кроме заголовков, автоматически дополняются точкой
   в конце, если они не заканчиваются на одну из литер '!,.:;?'.

10. Каждый считанный комментарий прикрепляется к ближайшему к нему объекту или,
    в случае обладания двумя звёздочками в конце, образует комментарий группы
    объектов (заголовок).

11. Есть 4 вида прикрепления комментариев к объектам:
   
   а) К следующему объекту.

      (** Модуль для яблок. *)
      MODULE Apples;

      TYPE
        (** Тип яблоко *)
        Apple* = RECORD END;

   б) К предыдущему объекту.

      CONST
        good* = 1; (** Сносное качество *)

   в) К следующей группе объектов (заголовок).

      CONST
        (** Общие постоянные **)
        maxApples* = 5;
        maxSeeds*  = 10;

   г) Комментарий находится внутри объекта.

      MODULE Apples;
      (** Это тестовый модуль. *)
      IMPORT Out;

      Apple* = RECORD (** Это комментарий должен быть на той же строке. *)

      PROCEDURE Init*(VAR a: Apple; seeds: INTEGER);
      (** Initializes apple a with the specified amount of seeds. *)
      BEGIN

      В случае, если есть два комментария к одному и тому же объекту -
      один перед и один внутри объекта, - они соединяются через перенос.

11а. Нюанс. В первом примере ниже первый комментарий после заголовка "Цвета"
     относится к соответствующей группе объектов, а комментарий "Чёрный"
     относится к следующему за ним объекту black. На это влияет ничто иное
     как вертикальный отступ, то есть расстановка переносов строк.

  CONST                                CONST
    (** Цвета **)                        (** Цвета **)
    (** Кодировка в 4 бита *)
                                         (** Чёрный цвет *)
    (** Чёрный *)                        black* = 0; (** Довольно тёмный *)
    black* = 0;
                                       CONST
    (** Красный *)                       (** Цвета **)
    black* = 0;                          (** Кодировка в 4 бита *)

                                         black* = 0; (** Чёрный *)

12. Для каждого типа объекта сохраняется дополнительная информация о нём:

    Для модуля     - название и импортированные модули, на которые есть ссылки
                     (при определении типов, переменных или параметров),
    Для константы  - имя и значение,
    Для типа       - имя и определение,
    Для переменной - имя и тип,
    Для процедуры  - имя, список параметров и тип возвращаемого значения,

    Для записи     - список полей,
    Для поля       - имя и тип,
    Для параметра  - имя, тип и способ передачи (по значению, VAR, IN, OUT).

13. Комментарии к группам объектов (заголовки) работают следующим образом:

    1) В рамках каждого вида объектов есть группы.

    2) Если группы не обозначены комментариями (нет заголовков) или часть
       объектов не входит ни в одну группу (не озагававлена), они заносятся
       в общую группу (в рамках каждого вида объектов).

    3) Объекты сортируются в алфавитном порядке внутри каждой группы. Но
       если группа целиком состоит из различных числовых или литерных
       постоянных, то сортировка не происходит и сохраняется исходный порядок.

       null = 0; apple = 1; pineapple = 2; other = 3;

    4) Комментарий-заголовок, в котором находится только знак минус приводит
       к тому, что идущие за ним объекты относятся к безымянной группе.

       (** - **)            (**-**)       (**   -  **)


                             ПРИМЕР ГЕНЕРИРУЕМОЙ
                        СТРУКТУРЫ ДАННЫХ ДОКУМЕНТАЦИИ
                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Используется произвольный наглядный формат с указанием типов данных (записей).
Помета "next ->" означает, что записи связаны в связной список. Предполагается,
что тип List обладает возможностью хранить связные списки различных типов:
Const, Var, Procedure, Type или Group.

Module {
  name = 'Apples'
  foreign = FALSE
  comment = 'Module Apples helps count apples. One can create ' +
            'a variable of type Apples.Apple, call Init and other ' +
            'procedures on it. Это тестовый модуль.'
  imports = ['Fruits']
  consts = List {
    Group {
      comment = 'Общие постоянные'
      body = Objects {
        Const {
          comment = 'Maximum amount of apples. Currently not used.'
          name = 'maxApples'
          value = '5'
        }
        Const {
          comment = 'Currently not in use.'
          name = 'maxSeeds'
          value = '10'
        }
      }
    } next ->
    Group {
      comment = 'Качество яблока'
      body = List {
        Const {
          comment = 'Неизвестное качество.'
          name = 'unknown'
          value = '0'
        }
        Const {
          comment = 'Сносное качество.'
          name = 'good'
          value = '1'
        }
        Const {
          comment = 'Отвратное качество.'
          name = 'bad'
          value = '2'
        }
      }
    }
  }
  types = List {
    Group {
      comment = ''
      body = List {
        Type {
          comment = 'Тип яблоко.[0AX]Represents an apple with some seeds.'
          name = 'Apple'
          form = recordType
          base = 'Fruits.Fruit'
          fields = List {
            Field {
              comment = 'Amount of seeds in the apple.'
              name = 'seeds'
              type = Type {
                name = 'INTEGER'
                form = namedType
              }
            } next ->
            Field {
              comment = 'Качество продукта, см. @Качество яблока.'
              name = 'quality'
              type = Type {
                name = 'INTEGER'
                form = namedType
              }
            }
          }
        }
      }
    }
  }
  vars = List {
    Group {
      comment = ''
      body = List {
        Var {
          name = 'applesCreated'
          comment = 'How many apples were created using Init.'
          type = Type {
            name = 'INTEGER'
            form = namedType
          }
        }
        Var {
          name = 'lastAdded'
          comment = 'How many seeds were added the last time, or -1.'
          type = Type {
            name = 'INTEGER'
            form = namedType
          }
        }
      }
    }
  }
  procedures = List {
    Group {
      comment = ''
      body = List {
        Procedure {
          name = 'Init'
          comment = 'Initializes apple a with the specified amount of seeds.'
          returnType = NIL
          params = List {
            Param {
              name = 'a'
              pass = byVar
              type = Type {
                name = 'Apple'
                form = namedType
              }
            } next ->
            Param {
              name = 'seeds'
              pass = byValue
              type = Type {
                name = 'INTEGER'
                form = namedType
              }
            }
          }
        } next ->
        Procedure {
          name = 'Reset'
          comment = 'Resets internal apple counter.'
          returnType = NIL
          params = List { NIL }
        } next ->
        Procedure {
          name = 'Shown'
          comment = 'Было ли приветствие.'
          returnType = Type {
            name = 'BOOLEAN'
            form = namedType
          }
          params = List { NIL }
        }
      }
    }
    Group {
      comment = 'Apple manipulation'
      body = List {
        Procedure {
          name = 'Add'
          comment = 'Adds n seeds to apple a.'
          returnType = NIL
          params = List {
            Param {
              name = 'a'
              pass = byVar
              type = Type {
                name = 'Apple'
                form = namedType
              }
            } next ->
            Param {
              name = 'n'
              pass = byValue
              type = Type {
                name = 'INTEGER'
                form = namedType
              }
            }
          }
        } next ->
        Procedure {
          name = 'Show'
          comment = 'Dispalys a message about the apple.'
          returnType = NIL
          params = List {
            Param {
              name = 'a'
              pass = byValue
              type = Type {
                name = 'Apple'
                form = namedType
              }
            }
          }
        }
      }
    }
  }
}

                      ПРИМЕР ПРЕДСТАВЛЕНИЯ ДОКУМЕНТАЦИИ

МОДУЛЬ Apples

ОПИСАНИЕ

  Module Apples helps count apples. One can create a variable of type
  Apples.Apple, call Init and other procedures on it. Это тестовый модуль.

ИНТЕРФЕЙС

  DEFINITION Apples;
    IMPORT
      Fruits;

    CONST
      bad = 2;
      good = 1;
      maxApples = 5;
      maxSeeds = 10;
      unknown = 0;

    TYPE
      Apple = RECORD (Fruits.Fruit)
        seeds, quality: INTEGER
      END;

    VAR
      applesCreated: INTEGER;
      lastAdded: INTEGER;

    PROCEDURE Add (VAR a: Apple; n: INTEGER);
    PROCEDURE Init (VAR a: Apple; seeds: INTEGER);
    PROCEDURE Reset;
    PROCEDURE Show (a: Apple);
    PROCEDURE Shown (): BOOLEAN;
  END Apples.

ИМПОРТ
  * Fruits

ПОСТОЯННЫЕ

  ### Общие постоянные ###

    * maxApples = 5
      Maximum amount of apples. Currently unused.

    * maxSeeds = 10
      Currently not in use.

  ### Качество яблока ###

    * unknown = 0
      Неизвестное качество.

    * good = 1
      Сносное качество.

    * bad = 2
      Отвратное качество.

ТИПЫ

  Тип Apple

    Apple = RECORD(Fruits.Fruit)
      seeds: INTEGER;  (* Amount of seeds in the apple *)
      quality: INTEGER (* Качество продукта, см. @Качество яблока *)
    END;

    Тип яблоко. Represents an apple with some seeds.

ПЕРЕМЕННЫЕ

  * applesCreated: INTEGER;
    How many apples were created using Init.

  * lastAdded: INTEGER;
    How many seeds were added the last time, or -1.

ПРОЦЕДУРЫ

  ### Apple manipulation ###

    * PROCEDURE Add*(VAR a: Apple; n: INTEGER);
      Adds n seeds to apple a.

    * PROCEDURE Show*(a: Apple);
      Dispalys a message about the apple.

  ### Другие процедуры ###

    * PROCEDURE Init(VAR a: Apple; seeds: INTEGER);
      Initializes apple a with the specified amount of seeds.

    * PROCEDURE Reset*;
      Resets internal apple counter.

    * PROCEDURE Shown*(): BOOLEAN;
      Было ли приветствие


              ПРЕДСТАВЛЕНИЕ ДАННЫХ О РАЗЛИЧНЫХ ТИПАХ В ПАМЯТИ

Общие поля типа любой формы:
  Type {
    comment = ...
    name = ...
    form = ...
  }

Непосредственно объявленный записной тип (RECORD):
  Type {
    ...
    form = recordType
    base = ...
    fields = List { ... }
  }

Базовый тип (INTEGER, BOOLEAN, CHAR и т. д.)
  Type {
    ...
    form = namedType
    name = 'INTEGER'           (или другое)
  }

Любой заранее объявленный именованный тип:
  Type {
    ...
    form = namedType
    name = 'Fruits.Fruit'      (или другое)
  }

Непосредственно объявленный тип-массив (ARRAY):
  Type {
    ...
    form = arrayType
    len  = 10                  (-1 для открытых массивов)
    base = Type { ... }
  }

Непосредственно объявленный указательный тип (POINTER):
  Type {
    ...
    form = pointerType
    base = Type { ... }
  }

Непосредственно объявленный процедурный тип:
  Type {
    ...
    form = procedureType
    procedure = Procedure { ... }
  }