* Damian Conway ([EMAIL PROTECTED]) [070613 22:46]:
> My underlying model is that documentation and the source it's documenting
> should be entirely orthogonal. So, to me, it would be very surprising if a
> programming construct (block comments) interacted with documentation. Or
> vice versa.
>
> * At the Perl 6 level, all Pod is syntactically and semantically
> invisible and therefore already equivalent to a comment.
>
> * At the Pod 6 level, all Perl code is merely meaningless ambient
> background noise and therefore already equivalent to whitespace.
We had a private discussion about this already three years ago: I
fully disagree! If the code and the documentation are not entangled,
why do you want to put them in the same file? Why do you put them in
the same distribution even?
No, the documentation is all about the code. The docs present everything
what the user should know about the code. The docs are the user's view
of the implementation, and the code is the computer's view on the same.
Realizing that, there are a few problems:
- is everything in the code documented?
- is everything documented correctly?
- during development, the interfaces change. Do we update the docs?
Getting people to document (and maintain the documentation) is not easy.
For some people, it's just not in their system. So, if you can make it
easier to do, if you can avoid the need for duplication (write it in
code, write the same again in the docs), if you can save some typing,
you probably end-up with better code.
Last week, I restructured the code of MailTools... published in 1995,
one of the oldest modules around. Also one of the most used modules
and described in many books. Changing the manual-page organization from
"at-end-of-file" to "interleaved" put the docs close to the respective
code. I found many mistakes in the docs, during this process: methods
which were not documented, methods which were not implemented, parameters
which were not or wrongly described...
As some people know, I wrote OODoc which extends the syntax of POD(5)
with logical markup and some simple avoidance of replication. For the
MailBox distribution (which is quite large), that saved me typing of
700.000 characters (35%)! Do you know how long it takes to type those?
So how much time did I gain to spend on code quality?
I had suggested syntax like this, in Perl6:
class Mail::Message {
`base class for message types
.has $msgid;
`The (internet wide) unique string which identifies this
`message object. May be undef as long as the message is
`begin composed.
.has $content_type = 'text/plain';
}
You see that there is little room for errors in the documentation.
Before people start flame-wars: the syntax is just to start a
discussion, to show how simple it could be. I am not stuck on that.
This can be automatically translated into (traditional POD like this)
(leaving out some blank lines for shortness sake)
=head1 NAME
Mail::Mesage - base class for message types
=head1 INHERITANCE
Mail::Message
isa Object
Mail::Message
is extended by Mail::Box::Message
=head1 METHODS
=head2 Attributes
=over 4
=item C<$msgid>
The (internet wide) unique string which identifies this
message object. May be undef as long as the message is
begin composed.
=item C<$content_type> (default 'text/plain')
=back
Damian, can you show how you would document the same code in POD6
syntax to get a comparible short man-page?
IMO: code and docs are two representations on one thinking processes,
named "programming". They are the opposit not orthogonal: parallel
developments with a little shifted focus.
The separation between State and Church is only about power: that the
Pope can't tell the President how to rule a country. But the people
need to merge their religious believes with their social duties.
Are you designing for "The Power" or "The People"?
--
Regards,
MarkOv
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
