About the program

                Generators documentation is a kind of software that automate the creation of the documentation of the source code. One of the most famous is the Javadoc documentation generator, which has become the de facto standard for documenting code in Java. Construction documentation takes place on the basis of the syntax of the programming language and specific comments, which must comply with well-defined standards to be accessible for machining.

                The benefits are well documented code clear:

- In co-development costs are reduced development time for code analysis, created by colleagues, or own a significant limitation of code;

- When entering into a new project developers reduced the time required to adapt them;

- A well-documented code easier to reuse. For example, in typical configurations are many versatile functions and procedures, but since they are practically not documented, many developers do not know about them and often create similar custom solutions.

                1C is long overdue need for the emergence of API documentation of standard configurations and its own generator documentation. But in addition to the template text "function (with title)", which allows to describe the parameters and return value of the subroutine, nothing in this regard, and has not appeared. Then I decided to create its own standard and documentation generator. He was named 1cdoc, by analogy with the Javadoc - a similar tool for Java.

application

                Documenting code is carried out by means of special comments, which must begin with the characters // ** // * or. Typical comments may be freely used in documented module. They do not affect the documentation.

Comments that start with the characters // ** are used to describe the entire module and are located at the beginning of the module to the variables, functions, procedures and comments from other species. If they are not found at the beginning of the module, it will be ignored.

Comments that start with the characters // *, used to describe the variables, functions, or procedures, and should be kept to describe objects.

Inside the doc comment tags are used. At this point, the following descriptors in 1cdoc system: @name, @desc, @author, @var, @param, @return. The purpose of each descriptor is described in the following table:

Example

Example code documentation for further processing 1cdoc is shown below:

 // ** @name Demo module 1cdoc
// ** @desc Example code description in the comments for later
// ** Create documentation using the documentation generator 1cdoc
// ** @author Jaroslav Volohov

// * @desc Unit test variables
// * @var Array DniNedeliMassiv {} stores the lowercase representation of days of the week
Move TekuschiyDenNedeli, DniNedeliStroka, DniNedeliMassiv Export;

// * @desc Converts delimited string into an array
// * @param {String} pStroka source string
// * @param {String} pRazdelitel string delimiter
// * @return {Array} array whose cells hold of the line
Function StrokaSRazdelitelyamiVMassiv (pStroka, pRazdelitel = "") Export

    Result = new Array ();
    MnogostrochnayaStroka = StrZamenit (pStroka, ";", Simvoly.PS);
    ChisloStrok = StrLineCount (MnogostrochnayaStroka);

    For Counter = 1 In ChisloStrok Cycle
        TekuschayaPodstroka = StrPoluchitStroku (MnogostrochnayaStroka, count);
        Rezultat.Dobavit (TekuschayaPodstroka);
    KonetsTsikla;

    Return result;

KonetsFunktsii

// * @desc StrokaSRazdelitelyamiVMassiv test using function ()
Test procedure ()

    DniNedeliStroka = "Mon, Tue, Wed, Thu, Fri, Sat, Sun";
    DniNedeliMassiv = StrokaSRazdelitelyamiVMassiv (DniNedeliStroka);
    Report (DniNedeliMassiv [1]);
    Report (DniNedeliMassiv [3]);

KonetsProtsedury 

After processing this module 1sdoc build report documentation mxl format, an example of which can be seen in the screenshot below (Screenshot №1).

Using the API

                For the program to work with 1cdoc use the following export functions called from the processing object module:

PoluchitStrukturuModulya () - makes the source code of the module as a string, parses it, returns the documentation in the form of a complex structure;

SozdatOpisanieModulyaVFormateMXL () - makes the structure of the documentation returned by the previous function, it returns a ready documentation in the form of a spreadsheet document.

                Detailed descriptions of these functions is the processing module object.

Full (commercial) version of the program

                Functional full version includes the following additional features:

- Documentation of the field added to the lists of callers and routines of each procedure or function within the module (Screenshot №2);

- Added an additional report on the challenges of the procedures and functions, which allows you to simulate and print a report every possible state of the call stack with a detailed description of routines in the stack (Screenshot №3).