pasdoc

Data wydania:26.06.2018

Pobierz: https://gitlab.com/bocianu/pasdoc/-/archive/master/pasdoc-master.zip

Kod źródłowy: https://gitlab.com/bocianu/pasdoc

---

Pasdoc jest narzędziem służącym do automatycznego generowania dokumentacji, na podstawie komentarzy w plikach żródłowych Pascala. Powstał na potrzeby dokumentowania mojego zestawu bibliotek BLIBS. Program napisany jest w javascripcie i działa jako narzędzie wsadowe, czyli uruchamiamy go i używamy korzystając z linii poleceń. Plik wyjściowy dokumentacji jest generowany na podstawie szablonu, który można sobie dopasowywać do własnych potrzeb - domyślnie jest to prosty HTML.

Wymagania

Aby uruchomić narzędzie pasdoc, wymagane jest nodejs w wersji 8 albo wyższej.
Aby pobrać żródła pasdoca, zalecam posiadanie gita.

Instrukcja instalacji

Jeśli mamy gita, to wpisujemy w terminalu:

git clone https://gitlab.com/bocianu/pasdoc.git
cd pasdoc
npm i

Jeśli nie mamy gita, to pobieramy i rozpakowujemy ręcznie, wchodzimy do katalogu i piszemy tylko:

npm i

Instrukcja użycia

Aby zobaczyć dostępne opcje, wywołajmy sobie wbudowaną pomoc programu

$ node pasdoc.js -h

PasDoc

  Generates html documentation from comments in pascal units.

Synopsis

  $ node pasdoc.js path_to_units
  $ node pasdoc.js --help

Options

  -h, --help                      Print this usage guide.
  -d, --dirpath path              Path to unit source files
  -o, --outpath path              Path to output html documents
  -t, --template template_file    Change default unit template.
  -i, --itemplate template_file   Change default index template.
  -n, --noindex                   Do not parse index file
  -s, --sortInterface             Sort Interface alphabeticaly
  -l, --language string           Change template language (default en)

Examples

  $ node pasdoc.js ../blibs -o ../blibs/doc
  $ node pasdoc.js . -l pl
  $ node pasdoc.js ~/my_pascal_libs -t ~/templates/unit.temp -n

Mamy tutaj nawet kilka przykładów, więc myślę, że nie będę się tutaj specjalne rozpisywał na temat poszczególnych opcji, jedynie wspomnę o rzeczach mniej oczywistych.

Program domyślnie wywołujemy dla wszystkich plików *.pas (bibliotek) jednocześnie. Muszą się one znajdować w jednym, źródłowym katalogu.

Podczas generowania dokumentacji domyślnie budowany jest plik indeksu, który jest listą odnośników do wszystkich pojedynczych plików dokumentacji bibliotek. Szablony wyjściowe definiujemy osobno dla biblioteki i osobno dla indeksu.

Opisy w plikach dokumentacji domyślnie generowane są w języku angielskim, możemy jednak to zmienić korzystając z odpowiedniej opcji. Domyślnie dostępny jest jeszcze język polski (pl). W mamy taką potrzebę, to w pliku langs.json możemy dopisać sobie kolejne tłumaczenia.

Instrukcja tworzenia dokumentacji

Aby dokumentacja była tworzona prawidłowo, musimy tworzyć komentarze w z góry ustalony sposób i przestrzegać kilku ważnych reguł.

Infomacje ogólne o unicie (bibliotece)

Aby udokumentować informacje ogólne, o całej bibliotece, umieszczamy analogiczny blok komentarza bezpośrednio pod deklaracją naszego unita:

unit unit_name;
(*
* @type: unit
* @author: John Doe <jd@mail.com>
* @name: My example unit.
* @version: 1.0.0
*
* @description: 
* This unit is created for some unknown purposes.
* This description is longer than one line, but every parameter can be that long.
*
* To break line in documentation, just leave one empty comment line.
*)

Zestaw obowiązkowych pól zależy wyłącznie od użytego szablonu. Szablon domyślny oczekuje pól: author, name i description. Nic jednak nie stoi na przeszkodzie, aby umieszczać tu jakiekolwiek inne dodatkowe informacje. Będą one dostępne w szablonie z poziomu obiektu main.body.

Aby linki w Twojej dokumentacji były "klikalne", zamknij je w nawiasach trójkątnych.

Opisywanie procedur i funkcji:

function nameOfSumingFunction(val1, val2: byte):byte;
(*
* @description:
* This function adds two bytes returning resulting value as an byte. 
* It just exists for documentation purposes, and it's description 
* is long enough to be separated into two lines. 
*  
* @param: val1 - first value to be sumed by my function
* @param: val2 - second value to be sumed by my function
* 
* @returns: (byte) - sum of val1 and val2 returned from my function 
*)

Procedury wykorzystują analogiczną konwencję, lecz nie zwracają one żadnej wartości. Pomijamy wtedy parametr @returns.

Dokumentowanie typów

type Days = (monday,tuesday,wednesday,thursday,friday,saturday,sunday);
(*
* @description: Enum type used to store days of week names.
*)

type TPoint = record 
(*
* @description: 
* Record type used to store coordinates of point. Descrption of it's 
* properties are just inline comments, and they are also parsed.
*)
    x: byte; // x coordinate
    y: byte; // y coordinate
end;

W podobny sposób powinniśmy dokumentować typy obiektowe:

type OBJ = Object
(* 
* @description: 
* Some object for doing stuff.
*)
    mem: pointer; // memory address of something
    size: word;   // size of same thing
    procedure Init(a: byte);  // Initializes object
    procedure DoStuff;        // Does important stuff
end;

Wszystkie metody obiektu mogą być dokumentowane w podobny sposób jak zwykłe procedury.

procedure OBJ.Init(a: byte); 
(*
*   @description:  Initializes object with mysterious byte value
* 
*   @param: a - mysterious byte to initialize object
* 
*)

Dokumentowanie stałych

const 
    SCREEN_WIDTH = 40;   // width of a screen
    SCREEN_HEIGHT = 24;  // height of a screen
    SIZE = SCREEN_WIDTH * SCREEN_HEIGHT // @nodoc 

Wszystkie stałe są automatycznie dodawane do dokumentacji, chyba że komentarz w ich linii zawiera frazę '@nodoc'. Takie stałe są omijane.

Opisywanie zmiennych absolutnych (rejestrów sprzętowych)

var 
    PMG_pcolr0: byte absolute $D012; // Player 0 color
    PMG_pcolr1: byte absolute $D013; // Player 1 color
    frameClock: byte absolute 20     // frame counter - @nodoc

Podobnie jak stałe, wszystkie zmienne absolutne są domyślnie dodawane do dokumentacji. Chyba że je wyłączymy przy użyciu frazy '@nodoc'.

Opisywanie zmiennych globalnych

var 
    PMG_base: pointer;      (* @var contains base address *)
    PMG_size: word;         (* @var contains memory size used by PMG *)

Aby umieścić dowolną zmienną w dokumentacji, musimy w jej wierszu dodać komentarz rozpoczynający sie od frazy '@var'.

Definicje szablonów

Domyślne szablony plików html, z których powstaje nasza wyjściowa dokumentacja, znajdują się w katalogu templates. Sa to dwa pliki *.thtml z szablonami biblioteki i indeksu, oraz plik styli CSS.

Możesz dowolnie modyfikować istniejące szablony, aby dopasować je do swoich indywidualnych potrzeb. Jako silnik kompilacji szablonu użyty został template Lodash.

Obiekt danych przekazywany do kompilacji szablonu pojedynczego unita ma następującą strukturę:

{
    main: {
        head: 'unit definition line',
        body: {
            // all parameters defined below unit declaration starting with @
            // like name, description, author, version...
        }
    },
    types: [ // array of all described types
        {
            name: 'name of type',
            type: 'type of type',
            desc: 'content of @description',
            record: [  // array of record properies (only for record types) 
                {
                    name: 'name of property',
                    type: 'type of property',
                    desc: 'description of property'
                },
                ...
            ]
        },
        ... 
    ]
    interface: [  // array of all described procedures and functions
        {
            head: 'procedure or function declaration line',
            name: 'name of procedure or function',
            body: {
                description: 'procedure description',
                params: [],  // array of params
                returns: []  // array of returned values
                // and any other defined properties starting with @
            }
        },
        ...
    ]
    consts: [  // array of constants
        {
            name: 'name of constant',
            value: 'value of constant',
            desc: 'description of constant'
        },
        ...
    ],
    regs: [  // array of absolute variables
        {
            name: 'name of variable',
            type: 'value of variable',
            addr: 'address of variable',
            desc: 'description of variable'
        },
        ...
    ],
    vars: [  // array of global variables
        {
            name: 'name of variable',
            type: 'value of variable',
            desc: 'description of variable'
        },
        ...
    ],
    lang: {
        // dictionary object containing fixed texts (header, footer...) in selected language
    }
}

Obiekt danych przekazywany do kompilacji szablonu indeksu bibliotek zawiera informacje o wszystkich bibliotekach i ma on następującą strukturę:

{
    indexData: [  // list of documents properties
        {
            head: 'unit definition line',
            body: {
                // all parameters defined below unit declaration starting with @
                // like name, description, author, version...
            },
            filename: 'name of html document'
        },
        ...
    ],
    lang: {
        // dictionary object containing fixed texts (header, footer...) in selected language 
    }
}

Przykładowa dokumentacja

Domyślny wygląd wygenerowanej tym programem dokumentacji możesz sobie sprawdzić na przykładzie dokumentacji moich bibliotek BLIBS.

Z generatora pasdoc korzysta także TeBe, autor Mad-Pascala, do generowania dokumentacji dla standardowych bibliotek dołączanych do pakietu. Można je zobaczyć tutaj: http://mads.atari8.info/lib/doc/index.html