" 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 < > [email protected]> wrote: > >> > >> On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <[email protected]> > 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 > >> > > > > >
