Best way to document AJAX + PHP code? [closed]

Question

I have always been for documenting code, but when it comes to AJAX + PHP, it's not always easy: the code is really spread out! Logic, data, presentation - you name it - are split and mixed between server-side and client-side code. Sometimes there's also database-side code (stored procedures, views, etc) doing part of the work.

This challenges me to come up with an efficient way to document such code. I usually provide a list of .js files inside .php file as well as list of .php files inside .js file. I also do in-line comments and function descriptions, where I list what function is used by what file and what output is expected. I do similar tasks for database procedures. Maybe there's a better method?

Any ideas or experiences?

Note: This question applies to any client+server-side applications, not just Javascript+PHP.

Answer 1

I think your method is pretty good. The only thing is that everything inside the js file is readable by others and therefore documenting what PHP files are used could lead to a security hole, in the off chance they can get to a file that returns something it shouldn't. Also, although not a big deal, on higher traffic sites, downloading say 500bytes of comments can add up.

Both of these are not big, but just thoughts I've had before.