On 2009-Aug-11, at 1:38 pm, raiph mellor wrote:
For a quick backgrounder, Larry had talked of reserving backtick for use as a user defined operator [1], Mark had suggested its use as a (tightly bound) comment [2], and James et al had suggested using it to declare units [3].
I'd like to see units, but as I've pondered it in the back of my mind, I've realised we don't need special symbols for them. A unit is just an object that has methods for converting to other units; sugar can be provided by postfix operators that cast their operand to the appropriate type: "42ft" calls "Unit::Length::Foot(42)".
I've long been in Mark's camp about a lightweight and attractive docstring syntax being likely to be helpful for encouraging habits that would likely contribute to improved long term maintainability of code with comments, and was mulling that.
Me too. It's not just making it easier to write documentation as you go -- and POD already makes it fairly easy -- but more than that, it's a matter of making it easier to *structure* that documentation. P6 is so powerful that equally powerful docs are going to be needed to take advantage of it. For example, there needs to be a way to pull out the docs for a specific function, or a specific parameter of a specific function: perldoc --module=Foo::Bar --method=baz --param=Title
In P5, there's a sort of coincidental structure available, in that you can put a chunk of POD next the function it describes, but the relationship needs to be more formal if, say, your editor is to be able to pull out that information to display it when you click on a keyword, or to auto-complete argument names, etc. Happily, Damian posted a while back that he is working on a way to associate docs with code.
The other problem related to that is the need for end-user documentation to have its own structure and order, which often will not be the same order supplied by the code. There needs to be a way to override and extend the structure, either by specifying a recipe for assembling the finished doc out of separate chunks of POD scattered about the code; or else by writing the docs in order and then link pieces the associated units of code.
(Of course, we're also faced with a poverty of tools: there's no technical reason we couldn't view the same file in "code mode" and "doc mode"... but it's no fun writing features that people can't use. On the other hand, nobody writes tools for features that don't exist, so you have to start somewhere.)
-David
