On Saturday, September 13, 2014 5:18:54 AM UTC-4, Stefan Karpinski wrote: > > There will always, however, be more documentation that doesn't affect the > behavior of the code. I'm not even sure what it means for that kind of > documentation to be "semantically meaningful" – you mean that it has a > specified format means something? >
If you can access the documentation from the code that creates it, without running any separate documentation-processing step, then it is semantically meaningful (and can affect the behavior of the code if the code so chooses). Also, our documentation will necessarily be tied to the semantics of the language -- for example, it can be tied to a Function in general or to a Method (as opposed to semantics-unaware documentation systems where functions can only be indexed by name), and I still have yet to see a clean way to do this with comments. Furthermore, I like having a clean separation between code comments (meant for programmers reading the source) and documentation (meant for users not looking at the source). But my biggest problem with using documentation in comments remains the lack of flexibility in formatting, metadata, etcetera. You're going to end up with either an inflexible system that is not easily extensible later to include richer information, or you're going to end up inventing your own mini-language for the docstrings (see the multiple PEPs on docstring formatting and metadata). We already have a pretty good language; why not use it? Would you want your choices of what can be represented in the documentation/metadata system right now to be dictated by formatting tools and environments circa 2004? circa 1994? How do you think Julia users will feel in 2024? In 2034? 20 years is not that long of a time for a living programming language; 10 years is about the time it takes to become mainstream.
