Why Docstring for Python stub is necessary

[Cirn09]

Yes, LIEF has Python port API. We can see all API easliy in any Python interpreter:

>>> import lief
>>> dir(lief)
['ARCHITECTURES',
 'ART',
 'Android',
 'Binary',
 'DEX',
 'ELF',
...
]

But lief is a pyd module. Our IDE don't know pyd's API, so we create stubs, let it tell IDE what API does LIEF has. Just as we discussed in #650

---

Yes, Python module LIEF has docstring. We can see it easliy in any Python interpreter.

>>> import lief
>>> help(lief.PE.parse)
Help on built-in function parse in module lief._lief.PE:

parse(...) method of builtins.PyCapsule instance
   parse(*args, **kwargs)
   Overloaded function.

   1. parse(filename: str) -> LIEF::PE::Binary
...

But lief is a pyd module. Our IDE don't know pyd's API and the Docstring of API, so we also need create stubs with Docstring, let it tell IDE what Docstring is for this API. Just as tttapa said:

I think this would be most useful for external C or C++ modules, because some IDEs don't look for signatures or docstrings in compiled modules.
Using stubgen at least fixes autocomplete for compiled modules, but if the stub files don't include docstrings, IDEs might not show any documentation when hovering over the function/class/variable in the editor (unlike with plain Python modules).
For example, Pylance in VSCode doesn't show documentation for functions in compiled modules, even with stub files generated by stubgen.

[romainthomas]

Our IDE don't know pyd's API

This is an IDE issue, not a LIEF issue:

• vim supports well this
• sphinx supports as well: https://lief-project.github.io/doc/latest/api/python/pe.html#parser
• the python interpreter/ipython recognize the doc.

I don't plan to address this request as it would mean duplicating the documentation in two places:

• the native module
• the pyi files

You should ask VSCode to address this limitation

[Cirn09]

I see. Since Vim already supports this, that makes discussion easier. (Before starting this discussion, I investigated VSCode and PyCharm, which do not support reading API and docstrings from pyd files. And indeed, some modules add docstrings directly to the pyi file.)
I will initiate a new discussion on the VSCode side.
Thank you very much for your patient and prompt response.