Documentation options

Randal L. Schwartz merlyn at stonehenge.com
Wed Jan 2 18:16:25 UTC 2008


>>>>> "Igor" == Igor Stasenko <siguctua at gmail.com> writes:

Igor> As i suspected, this discussion is going to nowhere, because of
Igor> conservative people like you.
Igor> There is no point to prove anything, if people simply don't want to
Igor> change anything.

And you're swinging to the extreme as well.  I'm all for change, but the
change to fundamental syntax and toolchain has a very high bar to jump for me.

Especially when options are *already* being proposed.  I like the idea of
teaching the browser to "[un]paste as comment" or "[un]comment this region",
doing the proper escaping and such.  Keep in mind that we already have a way
of uniquely putting a double-quote in a comment in the same way that we can
put a single quote in a string... just double it up!

I've also suggested other things in this thread and others.

Class comments are underutilized.  Let's start by at least putting
unstructured English in there.  That would help quite a bit.

However, we could also put *structures* into the class comments, as long as it
was backward compatible.  Maybe some form of wiki markup (Pier? Perl's POD?
ASCIIDOC?)  so that it could be mechanically translated when necessary.

I'd caution against overkill in this area though.  If it's difficult to use or
learn, IT WILL NOT BE USED by the very wide variety of folks that you need to
use it to make it a success.

I don't believe well-written methods need a lot of comments, so I'm unsure
what the drive is to get more structure into the methods.  However, I think
some proposal to have recognizable structure in a method comment would also be
interesting.

So, no, I'm not against change.  But I'm also practical.  Changing the
language means that we break compatibility with the past, and with other
smalltalks.  Smalltalk is about to have its second golden era.  Let's not kill
that before it starts.

-- 
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<merlyn at stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!



More information about the Squeak-dev mailing list