Hi Andrey,
I think this is a great proposition that can help many static analysis tools. However, it makes me very sad that you have chosen the docutils format for parameters and return types:
:type x: float
:param x: The X coordinate.
:type y: float
:param y: The Y coordinate.
:rtype: int
You should take a look at NumPy docstring conventions which are fully supported by Sphinx, and are actually human-readable.
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Here is an example:
Parameters
----------
x : float
The X coordinate.
y : float
The Y coordinate.
Returns
-------
int
Description of anonymous integer return value.
It also allows documenting object/class attributes, and exceptions.
—Vladimir
05.11.2013, 13:30, "Andrey Vlasovskikh"
The PyCharm team would like to propose a way for specifying and sharing API definitions of third-party libraries.
As there is not enough information in API definition code of Python libraries, developers of static analysis tools collect extended API data themselves and store it in their own formats. The absence of a common extended API information format makes it hard for developers and users of tools to collect and share data.
Our proposal is to create a common database of static API definitions with type hints as a collection of Python files called skeletons. Static analysis tools already understand Python code, so it should be easy to start extracting API definitions from these Python skeleton files. Regular function and class definitions can be extended with additional information, e.g. for providing types of function parameters and return values. Please read the details in the python-skeletons repository on GitHub: https://github.com/JetBrains/python-skeletons
Your comments and suggestions are welcome. We would like to collaborate on this initiative.
-- Andrey Vlasovskikh Senior Software Developer JetBrains http://www.jetbrains.com/ "Develop with pleasure!" _______________________________________________ code-quality mailing list code-quality@python.org https://mail.python.org/mailman/listinfo/code-quality