search

lunarmodules / Penlight

A set of pure Lua libraries focusing on input data handling (such as reading configuration files), functional programming (such as map, reduce, placeholder expressions,etc), and OS path management. Much of the functionality is inspired by the Python standard libraries.
https://lunarmodules.github.io/Penlight/
MIT License
1.93k stars 241 forks source link

Document `utils.execute` in utils.lua #479

Closed jlaurens closed 4 months ago

jlaurens commented 4 months ago

Document utils.execute function referred to in quote_arg documentation. BEWARE: this is not tested because I cannot build locally the whole documentation.

Tieske commented 4 months ago

this is a bit tricky, since all of compat is imported. So if we document this one, we'd need to document them all. Which then becomes cumbersome, since we'd need to update descriptions in multiple places.

Tieske commented 4 months ago

see https://github.com/lunarmodules/Penlight/blob/master/lua/pl/utils.lua#L4-L5

jlaurens commented 4 months ago

Well, we do not really need to document absolutely everything, only what is really used in the doc. The online documentation of quote_arg reads

Quotes a single (or list of) argument(s) of a command to be passed to os.execute, pl.utils.execute or pl.utils.executeex.

os.execute is a link as well as pl.utils.executeex, but not pl.utils.execute. Finding documentation for it is quite impossible for the average people. I myself digged into the sources and found the lines that you mentioned above. But this is not really what one would expect from an efficient documentation.