4 ms·
Interesting that you mention REPLs. I wonder if the often maligned Python docstring concept has/had more merit than it is currently given credit for.
by andybak 9y ago
Interesting that you mention REPLs. I wonder if the often maligned Python docstring concept has/had more merit than it is currently given credit for.
- moron4hire 9y agoI was not aware that docstrings were controversial in Python. Out of inspiration from Python docstrings, I have been occasionally working on a JavaScript structured documentation format that I call Pliny: https://github.com/capnmidnight/pliny https://github.com/capnmidnight/pliny It's all about creating a database of documentation that can be rendered to arbitrary formats. The documentation pages on the website for my big project are all completely generated by Pliny. I made it executable code rather than comments because I could iterate faster on the idea if there were a simple syntax to construct the database structure at the same time as writing the documentation, as well as by including the right setup script, I could have the database live-queryable in the REPL without any additional processing step. Unfortunately, there's nothing to verify that the documentation matches the code. There is a lot of type information there that would be super useful to exploit to statically analyze the code, but that'd be a big project to add that. It'd almost be easier to convert all of the code to TypeScript and recreate Pliny to extend a generated .d.ts typings file, so the doc gen could use just the typings file as the database.