You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apr.apache.org by "William A. Rowe, Jr." <wr...@rowe-clan.net> on 2004/11/29 16:44:18 UTC
Re: svn commit: r106663 - /apr/apr/trunk/CHANGES
/apr/apr/trunk/include/apr_file_io.h
At 03:26 PM 11/26/2004, you wrote:
>Author: stas
>Date: Fri Nov 26 13:26:37 2004
>New Revision: 106663
>
>URL: http://svn.apache.org/viewcvs?view=rev&rev=106663
>Log:
>rename the fopen defines (APR_READ, APR_WRITE, etc.) to have prefix
>APR_FOPEN_ (keeping the old defines)
Stas, you forgot doxygen @deprecate tags! For example, with;
>+#define APR_FOPEN_READ 0x00001 /**< Open the file for reading */
we need a matching doxygen entry redirecting the user;
>+#define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */
This provides documentation that devs *need* to track the changes.
Bill
Re: svn commit: r106663 - /apr/apr/trunk/CHANGES /apr/apr/trunk/include/apr_file_io.h
Posted by Stas Bekman <st...@stason.org>.
William A. Rowe, Jr. wrote:
> At 11:45 AM 11/29/2004, Stas Bekman wrote:
>
>>William A. Rowe, Jr. wrote:
>>
>>>At 10:50 AM 11/29/2004, Stas Bekman wrote:
>>>
>>>
>>>>Also should the deprecated macros stay in this file or can those be moved to some dedicated file to reduce the noise?
>>>
>>>They stay in place. During the next major+1 bump, the RM
>>>trawls through the files looking for @deprecated, and simply
>>>strips them out.
>>
>>That's not possible with this particular change, since everything (APR/httpd) still uses the old macros.
>
>
> No, it's a requirement when we push major+1. Then again,
> httpd may stay with 1.x, or may have a prerequisite 1.1
> (meaning we assume your change is there) or it may even
So when will it be possible to know whether it'll be in or not? If someone
decides to remove those later, why do I waste my time?
> move to 2.x - in which case we -must- update all occurrences
> within httpd.
Understood.
> There is no reason to keep using the old symbols in apr[-util/-iconv]
> so feel free to start migrating those.
I'll be working on symbols that I touch, at the moment I don't have to
time to work on other things. Once mod_perl 2.0 is out I may be able to
spend more time on other things.
>>>The way doxygen works, you would not want
>>>these moving out of scope to another file.
>>
>>Is there a way to put them in a different file and tell doxygen that the following entries really belong to a different file?
>
>
> 1. it isn't pretty and
>
> 2. you can't force a user to include another file from minor
> to minor bump. Their code should keep compiling w/o changes.
>
> Please don't worry that this seems 'polluted' - the next major
> bump cleans this all out. In the meantime, if they look for
> these symbols grep APR_FOO include/* they should find the old
> and new flavors in the same file, helping them with their own
> migration tasks.
Good point.
--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: svn commit: r106663 - /apr/apr/trunk/CHANGES
/apr/apr/trunk/include/apr_file_io.h
Posted by "William A. Rowe, Jr." <wr...@rowe-clan.net>.
At 11:45 AM 11/29/2004, Stas Bekman wrote:
>William A. Rowe, Jr. wrote:
>>At 10:50 AM 11/29/2004, Stas Bekman wrote:
>>
>>>Also should the deprecated macros stay in this file or can those be moved to some dedicated file to reduce the noise?
>>
>>They stay in place. During the next major+1 bump, the RM
>>trawls through the files looking for @deprecated, and simply
>>strips them out.
>
>That's not possible with this particular change, since everything (APR/httpd) still uses the old macros.
No, it's a requirement when we push major+1. Then again,
httpd may stay with 1.x, or may have a prerequisite 1.1
(meaning we assume your change is there) or it may even
move to 2.x - in which case we -must- update all occurrences
within httpd.
There is no reason to keep using the old symbols in apr[-util/-iconv]
so feel free to start migrating those.
>>The way doxygen works, you would not want
>>these moving out of scope to another file.
>
>Is there a way to put them in a different file and tell doxygen that the following entries really belong to a different file?
1. it isn't pretty and
2. you can't force a user to include another file from minor
to minor bump. Their code should keep compiling w/o changes.
Please don't worry that this seems 'polluted' - the next major
bump cleans this all out. In the meantime, if they look for
these symbols grep APR_FOO include/* they should find the old
and new flavors in the same file, helping them with their own
migration tasks.
Bill
Re: svn commit: r106663 - /apr/apr/trunk/CHANGES /apr/apr/trunk/include/apr_file_io.h
Posted by Stas Bekman <st...@stason.org>.
William A. Rowe, Jr. wrote:
> At 10:50 AM 11/29/2004, Stas Bekman wrote:
>
>
>>Also should the deprecated macros stay in this file or can those be moved to some dedicated file to reduce the noise?
>
>
> They stay in place. During the next major+1 bump, the RM
> trawls through the files looking for @deprecated, and simply
> strips them out.
That's not possible with this particular change, since everything
(APR/httpd) still uses the old macros.
> The way doxygen works, you would not want
> these moving out of scope to another file.
Is there a way to put them in a different file and tell doxygen that the
following entries really belong to a different file?
--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: svn commit: r106663 - /apr/apr/trunk/CHANGES
/apr/apr/trunk/include/apr_file_io.h
Posted by "William A. Rowe, Jr." <wr...@rowe-clan.net>.
At 10:50 AM 11/29/2004, Stas Bekman wrote:
>Also should the deprecated macros stay in this file or can those be moved to some dedicated file to reduce the noise?
They stay in place. During the next major+1 bump, the RM
trawls through the files looking for @deprecated, and simply
strips them out. The way doxygen works, you would not want
these moving out of scope to another file.
Bill
Re: svn commit: r106663 - /apr/apr/trunk/CHANGES /apr/apr/trunk/include/apr_file_io.h
Posted by Stas Bekman <st...@stason.org>.
William A. Rowe, Jr. wrote:
> At 03:26 PM 11/26/2004, you wrote:
>
>>Author: stas
>>Date: Fri Nov 26 13:26:37 2004
>>New Revision: 106663
>>
>>URL: http://svn.apache.org/viewcvs?view=rev&rev=106663
>>Log:
>>rename the fopen defines (APR_READ, APR_WRITE, etc.) to have prefix
>>APR_FOPEN_ (keeping the old defines)
>
>
> Stas, you forgot doxygen @deprecate tags! For example, with;
In my last patch I've asked:
> Should there be some deprecation tags for doxygen in it?
and received no follow up, so I've commited what I've proposed.
>>+#define APR_FOPEN_READ 0x00001 /**< Open the file for reading */
>
>
> we need a matching doxygen entry redirecting the user;
>
>
>>+#define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */
>
>
> This provides documentation that devs *need* to track the changes.
Thanks, committed.
Also should the deprecated macros stay in this file or can those be moved
to some dedicated file to reduce the noise?
--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com