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

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/)

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.

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).

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.