[squeak-dev] How may I contribute in documenting classes ?

Frank Shearar frank.shearar at gmail.com
Sat Aug 18 11:00:20 UTC 2012


On 18 August 2012 08:29, dimitris chloupis <thekilon at yahoo.co.uk> wrote:
> I am using squeak, I am learning it and I am loving it. I know its not
> perfect, I know it has it faults , but I feel I finally found an enviroment
> that I can do what I always want "live coding"
>
> As you can imagine as a begineer I spent a lot of time in system browser and
> I am suprised by the lack of documentation to some basic classes. Now I am
> probably the last person to qualify as a person to document those classes
> since my experience is very limited with Squeak and smalltalk.  But I feel
> that some documentation even if its a partial one , is better than no
> documentation. And since I am already reading so much of the souce , why not
> save people's time and mine (I can foget easily the code I read and so a
> documentation string can help me remember) by adding documentation strings
> to classes and their methods.
>
> The only things I dont know is how to make those documentations port back to
> squeak standard distribution. I assume would need some commit rights to the
> squeak source ?

I wholeheartedly agree that there are a whole pile of things in the
base image desperately needing comments. Your commits will be most
welcome!

Add your class comments, and use Monticello to save your edited
packages (as shown in the Monticello Browser) to the Inbox.

I don't have an image close at hand, but you should have the Inbox as
one of the repositories in the right hand pane of the Monticello
Browser. (If it's not there, we ought to add it as part of the
standard released image, so let me know.) If it's not there, right
click the "trunk" repository, select "edit repository info" and copy
that chunk of text. Cancel the dialog, and press the "+ Repository"
button. Paste in the text, and change "trunk" to "inbox".

Sometimes when you select the package you want to save you don't see
the repository you want to push to in the right hand pane. I often
find it easier to just save the package to my package-cache repository
and, from the version browser that pops up, just Copy the version to
whichever repo I want.

Once it's in the Inbox, the core devs can have a look at the class
comment, review it, ask you to change some things if necessary, and
they'll take care of pushing the comments into the Trunk.

frank

> ________________________________
> From: dimitris chloupis <thekilon at yahoo.co.uk>
> To: The general-purpose Squeak developers list
> <squeak-dev at lists.squeakfoundation.org>
> Sent: Saturday, 18 August 2012, 10:09
> Subject: Re: [squeak-dev] Why FFI is not included with latest squeak ?
>
> First thank you all for your answers. Suffice to say I have installed FFI
> from source.squeak , Win32 refuses to install for me(I am on MacoOSX if that
> is of any importance [Lion]).
>
> The argument that "we dont include FFI because we dont want to encourage
> people to use it instead of smalltalk" is something that does not convince
> me. FFIs exist included in implementations of all languages I have
> programmed with Python , Java, Common lisp (ccl) , Free Pascal etc . I was a
> python developer so far, ctypes which is the interface of python itself is
> used exactly because ( though its way slower than writing C extensions ) it
> allows coders to stick with python and make code easier to port across
> platforms. In my experience coders dont use FFIs just for the fun for it,
> because they are not fun , they can be a pain in the hat. Also a coder
> preferring FFI from the comfort of the amazing smalltalk debugger is
> something I have a very hard time imagining. People use FFIs because well ,
> they want to acess a functionality that the existing libraries just do not
> offer and that functionality exist on OS level anyway that will require some
> mangling with C. So no I dont think FFI will ever reduce the portability of
> squeak or that FFI libraries will start to pop up like mushrooms.
>
> Its not such an issue for me because : a) I can provide an image that will
> have FFI included b) unlike python squeak distribution system (monitcello)
> not only does not suck but seems to work quite well.
>
> " Many applications do not need FFI"  that could be said for a lot of
> smalltalk libraries already included with squeak. For example I have not
> seen many apps in squeak source make use of etoys ( I love etoys by the way
> and one of the reason I prefer Squeak from Pharo and is potentially
> necessary for a project I am making). I dont think that is a good excuse as
> well. Libraries dont need to be super popular to be included in a language
> implementations they are included to offer a more "complete" experience to
> the code as long they provide "basic" functionality and not something that
> is highly specialised.
>
> In any case I asked the question not because I want to force the inclusion
> of FFIs but because its the first time in last decade or so that I use a
> language implementation that does not come included with an FFI and tham
> made me curious about the reason behind this. In any case I love what you
> have done with Squeak, I really enjoy using it and even though it lacks
> documentation in several areas it really is easy to understand what is going
> on because of the overall architecture and the elegance of tools like
> inspector, and browser. Let me state all the above is my personal opinion
> and not an effort to play it smart or being rude, just geniune curiosity.
>
> ________________________________
> From: Bert Freudenberg <bert at freudenbergs.de>
> To: "ma.chris.m at gmail.com" <ma.chris.m at gmail.com>; The general-purpose
> Squeak developers list <squeak-dev at lists.squeakfoundation.org>
> Cc: The general-purpose Squeak developers list
> <squeak-dev at lists.squeakfoundation.org>
> Sent: Friday, 17 August 2012, 21:21
> Subject: Re: [squeak-dev] Why FFI is not included with latest squeak ?
>
> On 16.08.2012, at 22:28, Chris Muller <asqueaker at gmail.com> wrote:
>
>> Many applications do not need FFI, so it including would add
>> unnecessary (in many cases) bits to the footprint.
>>
>> FFI is a one-click install from SqueakMap, which can be accessed
>> programmatically via the Installer class, which is included with
>> Squeak.
>>
>> HTH.
>
> Right. Also, if we included it by default, people might think it is okay to
> use for providing basic functions. If FFI calls started to creep into the
> basic image we would lose the big advantage of platform independence.
>
> - Bert -
>
>>
>> On Thu, Aug 16, 2012 at 12:16 PM, kilon <thekilon at yahoo.co.uk> wrote:
>>> I was wondering why I need to install FFI and why it is not included by
>>> default. Any programming language I have used included at least a single
>>> FFI
>>> with it in its implementations or at least something similar.
>>>
>>> Is there a specfic reason why its not included ?
>>>
>>>
>>>
>>> --
>>> View this message in context:
>>> http://forum.world.st/Why-FFI-is-not-included-with-latest-squeak-tp4644264.html
>>> Sent from the Squeak - Dev mailing list archive at Nabble.com.
>>>
>>
>
>
>
>
>
>
>
>
>
>


More information about the Squeak-dev mailing list