[Phpmyadmin-devel] On the @uses comment tag
Hi, How the @uses tag should be used? I am randomly fixing some comments and would like to know what to do with them. I see it used to denote used global variables, internal PHP functions and phpMyAdmin functions. This should be cleaned up, at least by removing all mentions of internal PHP functions. -- Regards, Piotr Przybylski
Hi Dne Sun, 19 Jun 2011 23:30:53 +0200 Piotr Przybylski <piotr.prz@gmail.com> napsal(a):
How the @uses tag should be used? I am randomly fixing some comments and would like to know what to do with them. I see it used to denote used global variables, internal PHP functions and phpMyAdmin functions. This should be cleaned up, at least by removing all mentions of internal PHP functions.
Honestly I see no use for @uses, so I'd suggest to drop it completely as it anyway tends not to be updated with the code. -- Michal Čihař | http://cihar.com | http://blog.cihar.com
On Mon, Jun 20, 2011 at 11:59 AM, Michal Čihař <michal@cihar.com> wrote:
Hi
Dne Sun, 19 Jun 2011 23:30:53 +0200 Piotr Przybylski <piotr.prz@gmail.com> napsal(a):
How the @uses tag should be used? I am randomly fixing some comments and would like to know what to do with them. I see it used to denote used global variables, internal PHP functions and phpMyAdmin functions. This should be cleaned up, at least by removing all mentions of internal PHP functions.
Honestly I see no use for @uses, so I'd suggest to drop it completely as it anyway tends not to be updated with the code.
Since they are all in the same format and unique we could just run a regexp over all pma php files that removes those lines. Something like this (untested): replace('.'); function replace($dir) { $rdir = opendir($dir); while($file=readdir($rdir)) { if(is_dir($dir.'/'.$file) && $file!='.' && $file!='..') replace($dir.'/'.$file); else { $text = file_get_contents($file); $fp = fopen($file,'w'); fwrite($fp, preg_replace("/^\s*\*\s*@uses.*/m",'',$text)); fclose($fp); } }
-- Michal Čihař | http://cihar.com | http://blog.cihar.com
------------------------------------------------------------------------------ EditLive Enterprise is the world's most technically advanced content authoring tool. Experience the power of Track Changes, Inline Image Editing and ensure content is compliant with Accessibility Checking. http://p.sf.net/sfu/ephox-dev2dev _______________________________________________ Phpmyadmin-devel mailing list Phpmyadmin-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/phpmyadmin-devel
Hi Dne Mon, 20 Jun 2011 17:55:57 +0200 Tyron Madlener <tyronx@gmail.com> napsal(a):
Since they are all in the same format and unique we could just run a regexp over all pma php files that removes those lines. Something like this (untested):
replace('.'); function replace($dir) { $rdir = opendir($dir); while($file=readdir($rdir)) { if(is_dir($dir.'/'.$file) && $file!='.' && $file!='..') replace($dir.'/'.$file); else { $text = file_get_contents($file); $fp = fopen($file,'w'); fwrite($fp, preg_replace("/^\s*\*\s*@uses.*/m",'',$text)); fclose($fp); } }
Well there are many ways to remove it, but the question is whether we want to :-). PS: I would rather use: find . -name '*.php' | xargs sed -i '/^[[:space:]]*\* @uses /D' -- Michal Čihař | http://cihar.com | http://blog.cihar.com
Michal Čihař a écrit :
Hi
Well there are many ways to remove it, but the question is whether we want to :-).
I am reluctant to remove all @uses but I agree to remove the reference to internal PHP functions. Of course it's more work to maintain but I think that if we adhere to phpDocumentor principles, we should use @uses. Many people need to work with the source code and understand it. (I hope that one day, we'll have a working and up to date generated phpdoc at http://www.phpmyadmin.net/phpdoc/) -- Marc Delisle http://infomarc.info
Marc Delisle a écrit :
Michal Čihař a écrit :
Hi
Well there are many ways to remove it, but the question is whether we want to :-).
I am reluctant to remove all @uses but I agree to remove the reference to internal PHP functions.
Of course it's more work to maintain but I think that if we adhere to phpDocumentor principles, we should use @uses. Many people need to work with the source code and understand it.
(I hope that one day, we'll have a working and up to date generated phpdoc at http://www.phpmyadmin.net/phpdoc/)
Hmmm, I just saw your other message about DocBlox. -- Marc Delisle http://infomarc.info
Hi Dne Tue, 21 Jun 2011 07:52:31 -0400 Marc Delisle <marc@infomarc.info> napsal(a):
Michal Čihař a écrit :
Hi
Well there are many ways to remove it, but the question is whether we want to :-).
I am reluctant to remove all @uses but I agree to remove the reference to internal PHP functions.
Of course it's more work to maintain but I think that if we adhere to phpDocumentor principles, we should use @uses. Many people need to work with the source code and understand it.
I still fail to see what added value does it bring - somebody reading documentation and looking what function does does not really care what it uses underneath. For somebody working with the code, it only brings extra effort to keep it up to date. -- Michal Čihař | http://cihar.com | http://blog.cihar.com
Michal Čihař a écrit :
Hi
Dne Tue, 21 Jun 2011 07:52:31 -0400 Marc Delisle <marc@infomarc.info> napsal(a):
Michal Čihař a écrit :
Hi
Well there are many ways to remove it, but the question is whether we want to :-). I am reluctant to remove all @uses but I agree to remove the reference to internal PHP functions.
Of course it's more work to maintain but I think that if we adhere to phpDocumentor principles, we should use @uses. Many people need to work with the source code and understand it.
I still fail to see what added value does it bring - somebody reading documentation and looking what function does does not really care what it uses underneath. For somebody working with the code, it only brings extra effort to keep it up to date.
Here are situations I can think of: - someone changing parameters for a function; it would be interesting to see where this function is called - someone changing the format of a session variable or a global and wanting to see where this is used Does DocBlox answers these questions currently, if @uses is used? I believe that phpDocumentor did. -- Marc Delisle http://infomarc.info
Hi Dne Tue, 21 Jun 2011 08:53:37 -0400 Marc Delisle <marc@infomarc.info> napsal(a):
Here are situations I can think of: - someone changing parameters for a function; it would be interesting to see where this function is called - someone changing the format of a session variable or a global and wanting to see where this is used
You really can not rely on documentation in this case. Even if it would be accurate for all functions/methods, we have no such documentation for top level code blocks, which do include lot of of function calls. So using 'git grep FOO' will give you more valuable information than looking into doc.
Does DocBlox answers these questions currently, if @uses is used? I believe that phpDocumentor did.
It lists them, but does not provide back references to original objects (not sure if phpDocumentator did that, but it would be necessary for your use case). -- Michal Čihař | http://cihar.com | http://blog.cihar.com
Le 2011-06-21 10:03, Michal Čihař a écrit :
Hi
Dne Tue, 21 Jun 2011 08:53:37 -0400 Marc Delisle <marc@infomarc.info> napsal(a):
Here are situations I can think of: - someone changing parameters for a function; it would be interesting to see where this function is called - someone changing the format of a session variable or a global and wanting to see where this is used
You really can not rely on documentation in this case. Even if it would be accurate for all functions/methods, we have no such documentation for top level code blocks, which do include lot of of function calls. So using 'git grep FOO' will give you more valuable information than looking into doc.
Does DocBlox answers these questions currently, if @uses is used? I believe that phpDocumentor did.
It lists them, but does not provide back references to original objects (not sure if phpDocumentator did that, but it would be necessary for your use case).
So @uses is not that useful after all. -- Marc Delisle http://infomarc.info
Hi Dne Wed, 22 Jun 2011 06:14:31 -0400 Marc Delisle <marc@infomarc.info> napsal(a):
So @uses is not that useful after all.
That's what I think as well. Removed them from git. Should anybody dislike this, feel free to revert the commit. -- Michal Čihař | http://cihar.com | http://blog.cihar.com
participants (4)
-
Marc Delisle -
Michal Čihař -
Piotr Przybylski -
Tyron Madlener