"��It sounds a bit like there is no documentation at all"��

�� never implied this, and I refuse to believe that my wording can sound like that. I just say that the class comments are usually too small and many important classes are not��documented��at all. I don't know why you think I targeted you specifically with my comments.��

"terrible parts" is not the word I will use. I find the lack of documentation frustrating but that does not make the classes themselves "terrible". Pharo has its fair share of messy code but I have failed to see something I would call terrible.��

Its awesome that you spent large amount of time documenting, but all I said is that documenting key classes in the range of 10-15 lines each should not take a lot of time and pharo developers should do it. Thats my opinion, you are more than welcome to disagree or ignore it.��

I am willing to help any way I can. I am not willing to put blame on people.��

I do feel however because I believe I am a logical person that people that are introduced to Pharo will be��disappointed��in this department as I am. I think this is unfair to Pharo, because you guys have put a lot of effort in it that partly goes to waste.��Imagine��what would happen if people had easy access to the libraries , how many more would contribute and help pharo.��

I cannot imagine where I would be if there was no PBE or PFTE or the class comments that already are in there. For me any form of documentation is like bread and butter.��

Am I unreasonable ?��

I hope not.




On Fri, Jun 20, 2014 at 11:45 AM, Sven Van Caekenberghe <sven@stfx.eu> wrote:
I am a bit offended by the generalisations in your remarks, Kilon. It sounds a bit like there is no documentation at all.

There are several books, covering many of the high level aspects.

There is lots of documentation in the image, many class comments are pretty good, as are many method comments - even quite a lot of implementation comments can be found.

OK, there are some terrible parts as well, and some people seems to make a sport out of _not_ writing any comments at all - please call them out specifically, but don't generalise.

I have spent a large amount of time documenting all code that I published as well as writing separate high level documentation and tutorials for most of it as well as for Pharo in general. I know many others who did the same.

On 20 Jun 2014, at 10:10, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:

> I have not worked with spec a lot, but I think that it���s nice in terms of comments, they are very helpful. Also lately I���ve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
>
> Uko
>
> On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
>
>> yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
>>
>> Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
>>
>>
>> On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
>>
>> On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote:
>> Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
>>
>>
>> I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
>>
>>
>> --
>> Damien Cassou
>> http://damiencassou.seasidehosting.st
>>
>> "Success is the ability to go from one failure to another without losing enthusiasm."
>> Winston Churchill
>>
>