> I disagree. > > I don't like Java that much (for many reasons), but I have nothing but > respect for the massive amount of documentation that is easily accessible as > a direct result of JavaDoc. I personnaly feel that it greatly helped java > achieve the success it has. If all of parrot's module were that well > documented and that easily accessible, it would be a great boon in > recruiting followers.
I agree, but the dirth of comments has nothing to do with not having a commenting style like JavaDoc. In fact, most JavaDocs are useless. They usually are shallow and don't really help the programmer out that much. However, the point is moot because having or not having a "JavaDoc" like system has nothing to do with lack of documentation. > Also, localizing the code and the documentation allow programmer to keep > updated documentation more easily. Furthermore, since the docs will be in > the same files as the code, we can simply refuse to accept patches that do > not update the infile documentation. Thus preventing the horribly > problematic outdated documentation. I agree, but once again, this can be done as POD. > I say all of these things as someone who is new to this project and doesn't > know POD. If some of my statements here are in ignorant of the way things > are, please correct me. As I said, I am new to this and am waiting with > baited breath for this newbie start file. Nope, I think you are definately on track. However, the problem doesn't lie with POD. POD has the functionality and the tool support to be a useful documentation format. In fact, it has served the Perl community well for years. The problem is that the parrot project, like all open source projects, has developers with too much to do and too little time. Therefore, the code gets done slowly, with little documentation. This actually has a negative affect because it prohibits most newbies from getting involved because of lack of documentation. Since there are no fresh programmers coming in, and some of the old ones leave, the problem actually snowballs as there is more work and less people, so fewer comments get written. However, this has nothing to do with POD, just problems with the open source model in general. There are a HUGE number of benfits to open source projects, attracting "fresh meat" with ample comments just ain't one of them. Tanton
