# [ZEND-ENGINE-CVS] cvs: ZendEngine2(PHP_5_3) / zend_compile.c zend_highlight.c zend_language_parser.y zend_language_scanner.l /tests heredoc_001.phpt heredoc_002.phpt heredoc_003.phpt heredoc_004.phpt heredoc_005.phpt heredoc_006.phpt heredoc_007. - Thread: https://externals.io/message/35418 - Original archive: https://news-web.php.net/php.internals/35418 - Started by Hannes Magnusson on 2008-02-12T18:22:39+00:00 - Messages: 4 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #35418 — Hannes Magnusson — 2008-02-12T18:22:39+00:00 URL: https://externals.io/message/35418#35418 I would really really really really appreciate if the [DOC] tag was used more. While only random new features (or whatever requiring docs) are tagged with [DOC] it is totally useless as the doc team still has to browse through every single commit to figure out if there is something in it to document. To make matters worse; some new optional parameters/functions/whatever are disguised as bug reports with absurd summary and when they get fixed only "Fixed bug#xxx (foobar)" is added to the commit message and NEWS file... you really expect the doc team to actually _read_ the _commit_ and ignoring the commit message? Undocumented features are useless to the "general public". And no, your blog and/or article on/in devzone/php|arch is definitely not the place to write documentations if you want the feature to be used. On a related note: When reclassifying bug reports as "documentation problem" *please* mention what exactly it is that needs to be documented! Common guys, we can do a lot better here. -Hannes > dmitry Tue Feb 12 09:27:46 2008 UTC > > Added files: (Branch: PHP_5_3) > /ZendEngine2/tests heredoc_001.phpt heredoc_002.phpt > heredoc_003.phpt heredoc_004.phpt > heredoc_005.phpt heredoc_006.phpt > heredoc_007.phpt heredoc_008.phpt > heredoc_009.phpt heredoc_010.phpt > heredoc_011.phpt nowdoc.inc nowdoc_001.phpt > nowdoc_002.phpt nowdoc_003.phpt nowdoc_004.phpt > nowdoc_005.phpt nowdoc_006.phpt nowdoc_007.phpt > nowdoc_008.phpt nowdoc_009.phpt nowdoc_010.phpt > nowdoc_011.phpt nowdoc_012.phpt nowdoc_013.phpt > nowdoc_014.phpt nowdoc_015.phpt > > Modified files: > /php-src NEWS > /ZendEngine2 zend_compile.c zend_highlight.c zend_language_parser.y > zend_language_scanner.l > Log: > Added NEWDOC > > > -- > Zend Engine CVS Mailing List (http://cvs.php.net/) --- ## #35419 — Jani Taskinen — 2008-02-12T18:31:19+00:00 URL: https://externals.io/message/35418#35419 · In reply to: #35418 Please, when you give such feedback, please point finger at the persons who deserve it. Now it feels like everyone is "misbehaving" here. Not only mention the name in the body of the email but Cc: the mail to these people. Each and everyone who deserves to get spanked. And I'm not joking.. I myself have forgot to use the damn dog tag many times. (Which is it again, @DOC@ or [DOC] ? :) And if I forget, I'd like to be reminded. --Jani > I would really really really really appreciate if the [DOC] tag was used more. > > While only random new features (or whatever requiring docs) are tagged > with [DOC] it is totally useless as the doc team still has to browse > through every single commit to figure out if there is something in it > to document. > > To make matters worse; some new optional parameters/functions/whatever > are disguised as bug reports with absurd summary and when they get > fixed only "Fixed bug#xxx (foobar)" is added to the commit message and > NEWS file... you really expect the doc team to actually _read_ the > _commit_ and ignoring the commit message? > > Undocumented features are useless to the "general public". And no, > your blog and/or article on/in devzone/php|arch is definitely not the > place to write documentations if you want the feature to be used. > > On a related note: When reclassifying bug reports as "documentation > problem" *please* mention what exactly it is that needs to be > documented! > > Common guys, we can do a lot better here. > > -Hannes > > > > […] > -- Patches/Donations: http://pecl.php.net/~jani/ --- ## #35428 — Andi Gutmans — 2008-02-13T00:38:43+00:00 URL: https://externals.io/message/35418#35428 · In reply to: #35419 It's really hard to remember this stuff. Maybe we should make the system actually validate the messages when they are committed and reject the commit when tags are missing. For commits where a certain tag isn't relevant we could have an explicit way to skip it e.g. [DOC-NONE]. At least that way it's in the back (and front) of people's mind :) Andi > -----Original Message----- > From: Jani Taskinen [mailto:jani.taskinen@sci.fi] > Sent: Tuesday, February 12, 2008 10:31 AM > To: Hannes Magnusson > Cc: PHP Development > Subject: Re: [PHP-DEV] Re: [ZEND-ENGINE-CVS] cvs: ZendEngine2(PHP_5_3) > /zend_compile.c zend_highlight.c > zend_language_parser.yzend_language_scanner.l /tests heredoc_001.phpt > heredoc_002.phptheredoc_003.phpt heredoc_004.phpt heredoc_005.phpt > heredoc_006.phptheredoc > > Please, when you give such feedback, please point finger at the persons > who deserve it. Now it feels like everyone is "misbehaving" here. > Not only mention the name in the body of the email but Cc: the mail to > these people. Each and everyone who deserves to get spanked. And I'm > not > joking.. > > I myself have forgot to use the damn dog tag many times. (Which is it > again, @DOC@ or [DOC] ? :) And if I forget, I'd like to be reminded. > > --Jani > > > > > […] > used more. > > […] > tagged > > […] it > > […] > parameters/functions/whatever > > […] > and > > […] the > > […] nowdoc_001.phpt > > […] > nowdoc_004.phpt > > […] > nowdoc_007.phpt > > […] > nowdoc_010.phpt > > […] > nowdoc_013.phpt > > […] > zend_language_parser.y > > […] > -- > Patches/Donations: http://pecl.php.net/~jani/ --- ## #35434 — Derick Rethans — 2008-02-13T08:27:57+00:00 URL: https://externals.io/message/35418#35434 · In reply to: #35428 > It's really hard to remember this stuff. > Maybe we should make the system actually validate the messages when they > are committed and reject the commit when tags are missing. For commits > where a certain tag isn't relevant we could have an explicit way to skip > it e.g. [DOC-NONE]. At least that way it's in the back (and front) of > people's mind :) Uh, no thanks. I am perfectly caple of remembering if I need to use a tag or not and am not looking for somebody to hold my hands. The question is more *what* tag to use... @doc would definitely help. regards, Derick -- Derick Rethans http://derickrethans.nl | http://ezcomponents.org | http://xdebug.org