PHPDocumentor and documentation comments

Hi developers,

I have created documentation from MODx 0.9.6 branch with assistance PHPDocumentor and I have been very suprised. Any documentation commets of packages, classes and methods.
So I have created documentation from Revolution and I have been suprised very much because nothing have changed.

Why don’t you create documentation when you create new classes and methods ? If you don’t create this comments during creation, so creating this comments will be very hard in the future.

I am disappoint and I hope that this will rectified in next release.

Hi snop:

First, I don’t really understand what you mean. There are no PHPDoc comments on legacy or current MODx releases. All the PHPDoc comments for Revolution code documentation was written when I created that code. There are comments on almost all the classes and methods. They may not be the best comments, but it is open source and you’re free to discuss specifics regarding those code comments. Pretty much everything has changed in Revolution, so I really don’t know what you are disappointed in or talking about. You’re going to need to learn to better describe the issues you are bringing up.

You also continue to use phrases and words that seem to be accusational of our volunteer efforts to this project, and I for one am not appreciative of them. Saying something is "terrible" or implying "laziness", especially when what you’ve just described seems somewhat uninformed is not the kind of contribution we’re looking for.

Indeed, if you have the time and energy left from a full-time day job as well as family responsibilities to take on such an effort in your "spare" time for free, please add all of the PHPDoc type comments you feel appropriate. I’m sure everyone would appreciate your time and effort.

Quote from: OpenGeek at Sep 21, 2008, 10:23 PM

Hi snop:

First, I don’t really understand what you mean. There are no PHPDoc comments on legacy or current MODx releases. All the PHPDoc comments for Revolution code documentation was written when I created that code. There are comments on almost all the classes and methods. They may not be the best comments, but it is open source and you’re free to discuss specifics regarding those code comments. Pretty much everything has changed in Revolution, so I really don’t know what you are disappointed in or talking about. You’re going to need to learn to better describe the issues you are bringing up.

You are right that comments are in revolution much better. But fancy that you need use e.g. xPDO and you know that this library belongs among the best. Now you look at documentation(I mean as programmator so phpDoc comments) and you find out that comments are misssing or are very short.
So you write to the developers and you warn them about that. And this is the same. (But I have choiced bad phrases )

Quote from: OpenGeek at Sep 21, 2008, 10:23 PM

You also continue to use phrases and words that seem to be accusational of our volunteer efforts to this project, and I for one am not appreciative of them. Saying something is "terrible" or implying "laziness", especially when what you’ve just described seems somewhat uninformed is not the kind of contribution we’re looking for.

Why I have posted that message ? Because MODx is best CMS, I love him and I care about him.
Words as terrible or lazy are in my language normal and as I see in english not. So sry, if I have choiced bad words. I didn’t want offend anybody. So I deleted this words.
my message was meant as positive critique and not as inslut. In feature I will choicing my words better and carefully.
As I see now, I didn’t say that you are lazy but:
or developers will be very lazy create this comments in the future
and it’s essential diffrence.

So I want to apologize MODx dev team(but this was inadvertent).

Thanks snop.

Quote from: sottwell at Sep 22, 2008, 12:43 AM

Indeed, if you have the time and energy left from a full-time day job as well as family responsibilities to take on such an effort in your "spare" time for free, please add all of the PHPDoc type comments you feel appropriate. I’m sure everyone would appreciate your time and effort.

As I wrote, if comments aren’t creating when you are writing a code, so is very hard write this comments in the future. I know this very good from my own experience/practice
And my english isn’t good to do this.