Documentation options

I am looking to improve the options that we have available for in-image
documentation.

My first idea was to disable the compiler for methods of some classes,
overriding #compilerClass to return a slightly tweaked version of Null,
does this. However it only works for instance side methods.  Is it
possible to override #compilerClass for class side methods too. I assume
not, but I wonder if anyone knows for sure.

Secondly, my non-compiled non-smalltalk methods really trouble the
source code formatter. Can this be can be turned off on a per-class
basis too?

My second idea is a little more radical, but I think it could be useful.

I suggest giving the character $˚ a minor syntactical role, I fear the
floods of objections, but I will suggest the idea anyway, just in case
people have similar or useful alternatives to propose.

If the compiler only compiled code a) up to the first occurrence of $˚
if it is preceded by a CR, or b) up to and including a $˚ if followed by
a CR then the following would be possible...

A method such as this

myComplexMethod˚

explanation of complex method...

Shows up in the method browser next to the method it documents.

and a method such as this

myComplexMethod

^self

˚
Arbitrary documentation here....

===

I shall now duck and dodge the snowballs

Keith

A slightly less radical solution which would offer the same benefit
would be if the compiler stopped parsing if it encountered six or so
comment quotes on a line like so. (perhaps this could be reduced to two)

""""""

I was asked what problem this is solving...

1. In particular I find it difficult to provide code snippets in method
comments which work via select and do-it. particularly if these code
snippets are themselves commented. I think that tutorial type
documentation would benefit from this facility.

1b. Also I have a habit of putting test code in comments at the bottom
of my methods, but again I can't comment or use quote characters in this
code.

2. In some circumstances it is useful to use methods to hold data,
however the restriction that that data be valid smalltalk code is a pain
in some situations... i.e. the scripts in the dev image script manager
are maintained and generated from methods. However they have to be
manually pre-processed into valid smalltalk code escaping quotes and so
forth.

3. This scheme allows packages to have their own script manager like
documentation as classes within existing browser tools.

Keith

I guess what makes me reluctant to agree to the suggestions of having
more special characters with special syntactical meaning is that it
would only serve to complicate a language, one of whose most beautiful
aspects is its simplicity... I'm afraid it a) might become a slippery
slope for more of the same, and b) would make translation/portability
between different flavours of Smalltalk more difficult.

Just out of curiosity (not that I'd advocate this), would an
equivalent of the distinction between line comments and block
comments, e.g. in Java:

... some code ...
/* This is a block comment
   spanning multiple lines, including
   ... some more code ...
   // and even containing line comments
*/
... yet more code ...

give you what you're after?

Have you considered using other delimiters (such as curly brackets)
within comments to allow "double-click-and-do-it" execution?

Are you absolutely sure that class comments and protocols for "test
methods" won't do the job? In my experience, classes that are so
complex they need additional "documentation" should be broken down or,
if that's not at all possible, they should be thoroughly documented in
the class comment, with possible references in the methods (simply
"see class comment" should suffice). And class comments aren't parsed,
the code doesn't necessarily have to be valid, etc. Similarly,
consider breaking methods that absolutely need comments between lines
of code into smaller methods, so that you'll only need method comments
(even if those methods are only meant for testing/demonstration
purposes). But then, you probably knew people were going to suggest
that ;-)

Documentation for tutorials shouldn't necessarily all be in the code,
imho, there should be some accompanying medium like webpages or a PDF
or something (or a class comment?).

I realise this doesn't address all you were after, but maybe it'll at
least give you a few alternatives to consider =o)


On 1/2/08, Keith Hodges <[hidden email]> wrote:

Some languages, like Pascal stopping parsing source when reaching some point.

In Pascal it's the 'end.' sequence. You can put anything beyond that input.

In smalltalk, we also could have such feature: no reason to parse text
beyond the last return statement, because it's not reachable.

Interesting that current compiler barfs on code past the return
statement, saying that there's nothing expected after return.
I don't like such behavior: Sometimes i need to stub-out some code, to
test/debug methods, and i can't simply put ^self in the very beginning
of method (it forces me to put '[^self] value' instead, just to get
around such 'cleverness' of compiler ).
Very inconvenient and useless feature, as for me, and it can be simply
replaced by ignoring any input instead.

Igor Stasenko schrieb: Sorry, I consider silently ignoring program text rather problematic.
In my experience, putting something in comment quotes or inside "false
ifTrue: []" is pretty easy and preserves the simplicity.
If you want to be extra careful that such things never creep into
production code you could define a method BlockContext>>skipCode which
does just nothing, and wrap code to be skipped in "[] skipCode" :-) Of
course, you'd need to check for senders of this selector before
building, just as you would have to check for senders of #halt...

Cheers,
Hans-Martin

On 02/01/2008, Hans-Martin Mosner <[hidden email]> wrote:
What is the problem by ignoring things which is not going to work anyways?

> In my experience, putting something in comment quotes or inside "false
> ifTrue: []" is pretty easy and preserves the simplicity.

Commenting out the code is easy, if your method does not contain mix
of code/comments, so you can comment all the code in single block.
Otherwise you need to put "" in multiple places.. takes a lot of time
and it's stinks.. :)

> If you want to be extra careful that such things never creep into
> production code you could define a method BlockContext>>skipCode which
> does just nothing, and wrap code to be skipped in "[] skipCode" :-) Of
> course, you'd need to check for senders of this selector before
> building, just as you would have to check for senders of #halt...
>
There's a lot to consider in production code. You can put 'self flag:'
.. in places where you need return later. Why introducing another
method (skipCode)?

I don't see how restricting or not input past the last return
statement can make big difference.

Also, consider, that given change would help in documenting the
sources, and as side effect can help with quick hacks, which sometimes
needed when debugging the code.
I see more benefits that drawbacks.

> Cheers,
> Hans-Martin
>
>


--
Best regards,
Igor Stasenko AKA sig.

> Documentation for tutorials shouldn't necessarily all be in the code,
> imho, there should be some accompanying medium like webpages or a PDF
> or something (or a class comment?).
>
>  
It seems you cant please all the people all of the time. I started this
mode of thought when someone was insisting upon the value of
documentation that is not only available when online.

best regards

Keith

> Interesting that current compiler barfs on code past the return
> statement, saying that there's nothing expected after return.
> I don't like such behavior: Sometimes i need to stub-out some code, to
>  
I agree with you entirely on this one.

Does anyone have any idea as to how to implement this?

Keith

> test/debug methods, and i can't simply put ^self in the very beginning
> of method (it forces me to put '[^self] value' instead, just to get
> around such 'cleverness' of compiler ).
> Very inconvenient and useless feature, as for me, and it can be simply
> replaced by ignoring any input instead.
>
>
>  

Just as food for thought take into account that just silently ignoring what there is past the return statement is error-prone. That is why my opinion would be to be explicit in what you want to do and use comments.

What I think a nice change would be is to allow comments inside comments (that is, to only take into account the first and last ' " ' and accept everything that is inside). Maybe comments could be allowed past return statement.

0.05




--
Saludos,
Hernán

>>>>> "Keith" == Keith Hodges <[hidden email]> writes:

Keith> It seems you cant please all the people all of the time. I started this
Keith> mode of thought when someone was insisting upon the value of
Keith> documentation that is not only available when online.

There is clearly a happy medium between "the entire documentation
is on the web, making it useless when you are offline" and "we need
to invent a whole new compiler mode and source code chain just to
document something".

Please stop swinging between the extremes.

--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<[hidden email]> <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!

A better solution is to add a feature to the browser to "paste
comment" that ensures that the thing that is being pasted is entirely
a comment.  If the text being pasted already contains comments, it
will "do the right thing".

This change would be much easier to get other people to accept than a
change to the compiler.

People talk about language changes all the time, but they rarely
happen.  If you want to change Squeak, it is easier to do it by
changing tools or libraries, not by changing the language.

-Ralph

>>>>> "Ralph" == Ralph Johnson <[hidden email]> writes:

Ralph> People talk about language changes all the time, but they rarely
Ralph> happen.  If you want to change Squeak, it is easier to do it by
Ralph> changing tools or libraries, not by changing the language.

Agreed.

As I said a few months ago
in http://www.nabble.com/forum/ViewPost.jtp?post=12469219&framed=y

  I just don't like version creep in languages.  Smalltalk has remained
  relatively stable for nearly 3 decades.  Anything to disrupt that has got to
  meet a pretty high standard for me personally.

--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<[hidden email]> <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!

Ralph Johnson wrote: They rarely happen because the forward direction is too controlled, thus
ensuring that forks are the only option for progress on this front.

I am working hard to facilitate the forward direction being less
controlled, and to facilitate more integration between the forks if we
have newer branches. This is embodied in the "levelPlayingField" initiative.
> changing tools or libraries, not by changing the language.
>
> -Ralph
>  
some thoughts...

I am not sure what "the right thing" is in this situation.

Does this mean that the result is executable in place? Can it be copied
and pasted to another workspace and
still be executed as is?

Adding features to browsers is a lost cause now that there are so many
browsers to support with such features.

I am not sure that I want all of my comments/documentation to be in
green barely legible italics.

The option of finishing method parsing at a line beginning with """"""
is trivial to add to current systems in a safe way. I am using this for
the 'Sake' documentation. Once we have an example of this in use it
might be worth looking to put in place a more comprehensive solution.

cheers
 
Keith

On Wed, 02 Jan 2008 18:14:49 +0100, Randal L. Schwartz wrote:

:) agreed, in a sense. But the way that I am working is mobile as well as  
stationary, and since good old GERMANtrack has no mobile web access I  
browse things I need in advance and then switch the platform's browser to  
offline mode when travelling. There are also utilities (none of which I  
knew about that I can recommend) which populate platform browser's history  
and cache according to configurable lists.

So, what I'd like to see coming out of Keith's initiative is a  
standardized/able URL for accessing documentation by class name (and/or  
category name, method name), launchable by a tool (from the context of  
every Squeak browser view) on demand. That's the easy part [enhancing  
browser instead of compiler] :)

[0.0123*OT and the harder part] some time ago I tried to convince people  
to make available auto-generated, web searchable sourcecode pages from all  
public Squeak repositories and all I got so far (in addition to what was  
available by that time) are the project pages from SqueakSource (for which  
I thank the SqueakSource team very much, it's better than living in the  
dark century of software development).

But still no complete set of searchable web pages, with Squeak  
class+method sourcecode, from all that's published in the repositories,  
available :(

/Klaus

>

Randal L. Schwartz wrote: The whole point of smalltalk is that it is malleable.

The chunk format whose reading process can read literally anything comes
to mind as my favourite example of the power of this malleability.

So what is the point of implementing #compilerClass on Behavior, if it
becomes socially unacceptable to customize the compiler for different
situations, one of which is documentation.

=note We bemoan the fact that Squeak is lacking documentation (in-image)
yet we have very limited facilities for placing our documentation in or
alongside our code.

__END__

Keith

> Sorry, I consider silently ignoring program text rather problematic.

In Pascal (at least Borland's variant), it's not silent. You get a warning.

It could be done the way undeclared variables are in OBSystemBrowser.  
(Cancel/save)

On 02/01/2008, Randal L. Schwartz <[hidden email]> wrote:
As i suspected, this discussion is going to nowhere, because of
conservative people like you.
There is no point to prove anything, if people simply don't want to
change anything.
If you don't want to change, don't want to move on, then squeak's
destiny is to vanish and be forgotten when last living mammoth will
die.

Do we need a better tools/ways for delivering content(documentation)
to developers? Yes we are!
So, please, can you, instead of rejecting proposals, which are
incompetent or which can't stand under pressure of your high
standards, propose own solution?

--
Best regards,
Igor Stasenko AKA sig.

Keith Hodges wrote:
> A slightly less radical solution which would offer the same benefit
> would be if the compiler stopped parsing if it encountered six or so
> comment quotes on a line like so. (perhaps this could be reduced to two)
>
> """"""

Upon reading this, I thought to myself: Each class has a classComment,
which has its own stamp, and browsers have a separate pane for editing
classComments. Perhaps methods could have a comment instance variable,
too, and the browsers could let you edit the comment separately from the
source code!

Then I went looking. CompiledMethod is a direct subclass of ByteArray,
and has no instance variables.

This is one of the weaker areas of Smalltalk: its self-representation is
not particularly object-oriented.

Regards,
  Tony
--
 [][][] Tony Garnock-Jones     | Mob: +44 (0)7905 974 211
   [][] LShift Ltd             | Tel: +44 (0)20 7729 7060
 []  [] http://www.lshift.net/ | Email: [hidden email]

> So, what I'd like to see coming out of Keith's initiative is a
> standardized/able URL for accessing documentation by class name
> (and/or category name, method name), launchable by a tool (from the
> context of every Squeak browser view) on demand. That's the easy part
> [enhancing browser instead of compiler] :)
I am hoping that Squeaksource2 is based upon pier, so that projects can
have bookmarkable urls and so can put up documentation and attachments
that are relevant to their projects and the classes therein. With any
luck this will enable a class to link directly to its documentation
which is in reasonably accessible known place.

Until that happens I am using installer.pbwiki.com as a place to put
"standardized/able URLs for accessing" installation scripts in a similar
manner.

Keith

On 02/01/2008, Blake <[hidden email]> wrote:
> > Sorry, I consider silently ignoring program text rather problematic.
>
> In Pascal (at least Borland's variant), it's not silent. You get a warning.
>
> It could be done the way undeclared variables are in OBSystemBrowser.
> (Cancel/save)
>
>
That's exactly what i proposing: instead of barfing and rejecting to
compile at all  (btw, when, putting a code beyond return statement
considered as syntax error?)
ask developer to ignore this code (because it's simply unreachable) or
cancel saving the method.

--
Best regards,
Igor Stasenko AKA sig.