Mark Overmeer wrote: > 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.
I agree.
And while writing a class in Perl 6 the other day I noticed that copied
& pasted the signature of method to the pod:
=begin pod
=head3 C<method from_string(Str $s);>
initialize the Sudoku from a string C<$s>, with a 0 denoting an empty cell
and a number between 1 and 9 a clue.
Note that there is currently no way to use this function for sizes bigger
than 9x9 overall length.
=end pod
method from_string(Str $s){
# implementation of that method here
}
Since method signatures are very expressive in Perl 6, there should be a
way of accessing them in the POD without copy & paste. If you don't
think that's necessary: try it out for yourself. Write a class and
document it properly. I'm sure you'll end up doing the same as I did.
ATM I don't know that should be implemented, but perhaps somebody else
can think of a good way.
--
Moritz Lenz
http://moritz.faui2k3.org/ | http://perl-6.de/
signature.asc
Description: OpenPGP digital signature
