All such tools do is give an overview of what components exist, and actually you get no new information than what the PJX gives itself.
What can help bring together condensed information about how things work in your project is having comment headers in each function/procedure of PRGs and method of classes, but that's also not automatic, so indeed I second Mike in pointing out comments are important.
More complex and may be less intuitive components better have extra documentation describing them, so really write out a word document. But indeed the intuitiveness of a library isn't the main reason to do so, complexity'/size, too and an overall overview of components, as documentation should be. It is asked too much of a documenting tool to find the topics/realms of any project and structure documentation the way you can do yourself. Especially in VFP where it is far more usual everything is in one project. In .NET it's much more natural to make several assemblies (DLLs) used as compartments of an overall project, in VFP your DLLs are more like the VCXes and PRGs that encapsulate a set of functions/functionalities.
What no documenting tool can handle for you is giving more insight into the working of your code than you can by such real documentation, what it may do more than what VFPs wizard or PDM does and what I haven't seen done is the automatic extraction of dependencies, who creates and uses which objects, which methods and how and then other metrics like simple the length of methods/functions/procedures can tell you where code may be going against good measures.
One API-project I provided as an APP (really a VFP APP file) was a database interface that became something like a service structure or web service was today, just not centralized in an intranet server, but in VFPs typical client way at the client-side. You created a specific class "interface" via NewObject() specifying the app file and so used it a) without compiling it into your own PJX and b) could update for the same reason without the need to change any other code, as long as changes were made compatible.
In this interface project, I explicitly added a method "documentation" into classes, that was only consisting of comments, describing the whole class, on top of the description in any method header zo have overview documentation.
And a typical header comment section should besides simple information like author/company/date of creation/change contain a method description, tell what the method does, what parameters mean and which are mandatory or optional and give an example.
And on top of that, a test method also was introduced, but that was later put into a separate unit test project running all interface methods with test calls. The topic of database interface made it very testable, too, as that didn't include any forms and user interaction, mainly something that could also have been made as stored procs of a database, but also when data of multiple DBCs and also MSSQL Server databases was involved, so really a centralisation of business logic about the whole database landscape.
The principles also apply to normal projects, though, especially having comment headers. But they don't fall from the sky or are about information in the PJX, VFP will not note which Windo account worked on which code on which date, you don't even get such simple chronologic information from a documentation tool if you don't put it inside comments while you work.
Bye, Olaf.
Olaf Doschke Software Engineering
