Forum OpenACS Development: Documentation: let's find the old stuff and make it useful again

I've noticed when looking at the API browser that functions I look up don't have any explanitory text in them. So, this was going to be a "Lets get going with docs writing!", and, indeed, I do want to do that. But I have found an important subtask that would be useful to be completed first in order to streamline the larger "Let's make sure everything is documented" effort.

Rather than contact anyone too early in the process, I decided to start on my own to write documentation for one file that's fairly close to the core (and that I was trying to understand at the time), then I switched to doing the TCL procs that themselves deal with documentation (since I'd have to learn about them in this process anyway).

Lo and behold, the docs are there! The problem is twofold:

1. the docs that do exist in the TCL files of OACS's inner core are in TCL comments rather than being in doc strings which are part of ad_proc; and
2. that documentation that exists there has evidently been ignored for many years. The listing shows item names (of parameters and even of the procs themselves) that are no longer the same as that they are there to document, among other phenomina.

The good news is there is a lot of documentation that is relevent and correct. Let's arrange to incorporate it:

I'm now on something of a crusade to move the docs from the # comments where they now exist to the doc string place in the ad_proc for each tcl proc. (why am I on this kick? because new developers can use the help.)

Due to (2) above, some of that documentation is relevent, and some not. The reason for this is apparently that while code changed, the docs were not changed and sorta stayed in the file attached by proximity to something it doesn't really refer to any longer.

So, my intent is to rewrite some of them, and just move others in with a FIXME tag which would appear to those who call up the procedure in the API browser.

I'd like to ask for some resources in this process; the most important of which would be other people who want to help with this process. The other is a folder somewhere in openacs file-storage where I can add files and folders.

In fact, we need to get our developers to understand the importance of documentation. Code _and_ document instead of "code, code, code. Documentation? What's that?"

* Got rid of all the proc_doc's
* Moved comments that were outside or in function comments to within
  ad_proc documentation block.
* Added documentation where it was missing and I could figure out what 
  the function was supposed to do.
* Added explanation as to why the function was deprecated where I knew 
  the reasons.

I just saw Yon's message about the reasons for ad_parameter being deprecated, so I'll commit that now. I tested and everything is go.

• First, here's the diff that makes ad_proc collect one more needed piece of information.
• Finally, here's the APM package that produces and renders the report.

Happy hunting.