Форум PHP

Значит все не так прекрасно, как описано axillом, ч.т.д.
ЗЫ: но на рассылку подписался, может действительно пришлют че ценного?...

Значит ответственные за рессурс, не следят за тем чтобы в присланных им классах были комментарии. А остальное зависит от программиста написавшего класс.
Тогда мне повезло больше, вот класс ArrayLIst ->

В приложении класс оттуда, сам комментарии не удалял, честное слово!
Сколько посмотрел - все так же задокументированы (закомментированы)...

>ГДЕ???
Внутри самого класса.

Кстати , я оттуда скачал класс ArrayList, чего уж больно не хватало для ООП. Работает как класс ArrayList в Яве или его аналог в C#.
Это массив для управления объектами.
ООП на 5-м PHP вполне функционально, и можно собрать кое-что интересное, удобно разбив классы на категории: логические объекты, бизнес логика, база данных, ну и отделив интерфейс.

axxil
>>>Там доволно хорошо задокументированы классы и легко разобраться что какой метод делает.
ГДЕ??? Че-то не нашел документацию ни для одного класса...

Затем же, зачем пишут комментарии к законодательству - законы же вообще то на русском языке написаны, только вы заранее не знаете без судебной практики как они себя в суде поведут и сколько нужно заплатить тому или иному судье, чтобы закон вёл себя так, как вам нужно :))) Там же и здесь вы можете догадываться подсознанием и догадываться правильно, но не составлять же индексный указатель по догадкам, легче это оформить в книгу и пользоваться ей.

У меня имеется справочник по Linux командам в бумажном виде, я с удовольствием им пользуюсь, хотя man, а уж тем более info более поный - на странице больше убирается текста, и русский текст со страницы я воспринимаю быстрее, чем английский с монитора. Тоже касается Windows API, да в заголовочных файлах вы найдёте много больше, чем в бумажных справочниках, которые устаревают, не успев быть выпущенными, но в справочниках приводятся примеры и патерны, которые работают и используются другими программистами, что в заголовочных файлах неприемлемо. Книги - это комментарии к излишне локаничным заголовочным файла, стандартам и мануалам.

Тогда непонятно зачем пишутся объёмные справочники по библиотекам того же С++ или Windows API
Там ведь тоже говорящие названия...

Ничто не мешает не указать комментарии - класс будет работать и без них, а пишут их от того, что девать некуда. Самодокументирующий код, это вот что, это когда я смотрю на метод validate_extension_list() и понимаю, что он мне вернёт список, причём расширений и правильный и что самое главное ему при этом можно не передавать никаких параметров, в этом рое мыслей я даже не отдаю отчёта - он сам рождается, только из названия и прототипа метода. Код самодокументируется за счёт правильно выбранных названий и согласованного интерфейса.

Вот тут немного непонятно.
Конечному пользователю интересны только public методы. А всякие служебные private пусть себе торчат в базовом классе.
А описание методов абстрактного класса это уж user guidе, без этого никуда. Тем более что всё описание сводится к строкам (прямо внутри класса в качестве комментов) типа:

/**      * Basic validation and parsing of a passed extensions parameter      *      * - This method does *not* check whether the extensions passed *are* real-life extensions,<br>      *         i.e. it does not spell check nor check against a list of 'known' extensions.      * - If no parameter is passed or the parameter passed is not a string nor an array      *         it defaults to the class default      * - If the passed $exts are the same as the last time this method was used, the check will      *             be skipped and the results of last time will be used for efficiency      *      * @access     private      * @uses     $last_passed_exts    for efficiency check / sets the variable if the current      *                                 passed $exts is different      * @uses     $last_exts            for efficiency if the passed exts were already checked /      *                                 sets this variable for same use if the passed $exts was      *                                 different      * @uses     $exts                to default to if no valid extensions parameter was passed      * @param    array|string    $exts    [optional] extensions parameter to validate      * @return    array|string    array of extensions or the string 'all'      */     function validate_extension_list( $exts = null )

которые в дальшейшем, с помощью phpDocumentatorа, сводяться в хороший help.

PS А что такое самодокументирующийся код?

Отчасти соглашусь, однако когда потребуется узнать чем богат метод, какие методы предоставляет, вы обратитесь к конечному классу, а к абстрактному, так как конечный класс помимо абстактных методов, предназначенных для реализации полиморфизма содержит и другие дополнительные методы. Классы получаются не самодокументированные, чтобы пользователи-программисты не лазили в код, для них приходится писать документацию, а поддерживать её сложнее, чем самодокументирующийся код.