Автодокументирование
====================

QuickAPI построено таким образом, чтобы программисту было предельно 
просто писать не только сам метод API, но и документацию к нему.

Как вам должно быть известно, в Python любой текст, расположенный в 
самом начале описания класса или функции - является документацией к нему::

    #!/usr/bin/python
    # -*- coding: utf-8 -*-
    # Copyright 2015 Ivan Ivanov <example@example.com>
    """
    Документация к модулю
    """

    class MyClass(object):
        """
        Документация к классу 
        """

        def mymethod(self, *args, **kwargs):
            """ Документация к методу класса """
            return

QuickAPI использует эту особенность, но текст документации должен быть
в формате Markdown.

Например::

    def my_api_method(request, code, data=None):
        """
        ### Назначение

        Устанавливает что-то из чего-то, и что-нибудь возвращает,
        допустим, список лекарств.

        ### Параметры

        1. "code" - код чего-то;
        2. "data" - какие-то необязательные данные;

        ### Ответ

        Список добавленных лекарственных средств

        ```
        #!javascript
        [
            {"title": "Анальгин", "count": 10, "created": "2015-01-01T00:00:00Z" },
            {"title": "Аспирин", "count": 20, "created": "2015-01-01T00:00:00Z" },
        ]
        ```
        """
        
        now = datetime.now()
        data = [
            {'title': 'Анальгин', 'count': 10, 'created': now },
            {'title': 'Аспирин', 'count': 20, 'created': now },
        ]
        return JSONResponse(data)

И на вашей странице API получится примерно такое описание к методу:

.. image:: img/autodoc001.png

.. _wiki-autodoc-multilanguage:

Если же вы создаёте приложение с поддержкой нескольких языков и желаете 
сделать страницу API тоже мультиязычной, то посмотрите как мы 
переделаем предыдущий пример, чтобы реализовать отложенный вызов перевода 
документации::

    from django.utils.translation import ugettext_lazy as _
    from quickapi.utils.doc import apidoc_lazy, string_lazy

    def my_api_method(request, code, data=None):

        now = datetime.now()
        data = [
            {'title': 'Анальгин', 'count': 10, 'created': now },
            {'title': 'Аспирин', 'count': 20, 'created': now },
        ]
        return JSONResponse(data)

    my_api_method.__doc__ = apidoc_lazy(
        header=_("Устанавливает что-то из чего-то, и что-нибудь возвращает, допустим, список лекарств."),

        params=string_lazy(
    """
    1. "code" - %s;
    2. "data" - %s;
    """, (_('код чего-то'), _('какие-то необязательные данные'))),

        data=string_lazy(
    """
    %s

    ```
    #!javascript
    [
        {"title": "Анальгин", "count": 10, "created": "2015-01-01T00:00:00Z" },
        {"title": "Аспирин", "count": 20, "created": "2015-01-01T00:00:00Z" },
    ]
        ```
    """, _('Список добаленных лекарcтвенных средств')),
    )


Конечно, такой подход вносит сумбур в структуру кода, но это того стоит.