Documenting dependencies

[andyH]

I routinely add comment headers to all functions/procedures - what they do, why they do it, any problems encountered, parameters passed, short change history, etc. So in six months time when I have to make a change I have some idea of what I was doing. I also have a 'used by' field in the header - within the application what other functions/procedures use this function/procedure?

This is not a unique requirement, so I thought before developing a program to do this I'd ask if one already exists?

What I have in mind is a program that scans a unit to extract a list of functions, then scans all units in the application and lists the function/procedures using that function and the lines where it is called. Alternatively, type in a function/procedure name and it will tell you where it is used.

Once that is done, it would also be useful to have the reverse - for any procedure what functions/procedures does it use?

Does it exist?

[MarkMLl]

I'm not aware of its already existing, but I'm not a heavy user of the various IDE addons... I find they get in the way.

I anticipate that you will have problems with polymorphism and inheritance: I remember previous discussion where various "old school" programmers bemoaned the lack of decent xref facilities although in that context they were looking for pure compiler listing output rather than an edit-time helper.

MarkMLl

[Warfley]

I don't think it is so good to write that into a comment (which requires regular maintainance), but rather just do the search whenever you need it (modern PCs are so fast you can search your whole project in a matter of secodns).
And this is somethin Lazarus already provides. I think the hotkey is Ctrl + Shift + I (or simply rightclick your function and it has somewhere a find all references menu entry).

[440bx]

Long ago, there was a product named "Turbo Analyst" that was based on those ideas.  The product is long dead by now but, it was useful (I used it.)

Today, I think only the compiler could have a chance to provide the information you seek and, even then, it would be difficult and not necessarily as useful as one may think at first.  For instance, as MarkMLI mentioned, inheritance and polymorphism could create ambiguous/confusing situations, not to mention function/procedure overloading.

Interestingly, what you are referring to seems to work better at the assembly level than at the source level.  For instance, IDA Pro cross references the "called from" and "called by" and that is quite useful at the assembly level.  The important thing is that at that level most source-level ambiguities are no longer present.  What's undecidable are the indirect register calls which can only be determined at run time (often a result of polymorphism.)

[wp]

I routinely add comment headers to all functions/procedures - what they do, why they do it, any problems encountered, parameters passed, short change history, etc. So in six months time when I have to make a change I have some idea of what I was doing. I also have a 'used by' field in the header - within the application what other functions/procedures use this function/procedure?

That's an honorable idea. But on the other hand, there is an extremely high chance that it will not be up-to-date for long. You add some new code and call an existing function - and forget to update the "used by" field. Or maybe you don't, but a few days later you notice that this function is not needed in the new code any more - another chance to forget to update the "used by" field.  The same with the arguments of a procedure: in a living project there is always the possibility that you must add a new argument. This means that you must update all occurencies where the new argument must be inserted - this is what the compiler tells you. But it does not tell you that you must also update the parameter list in the comment header.

Once your documentation has run out of sync it has lost much of its value...

It think it is much more important that you learn how to navigate the source code, how to find a procedure - then you see its arguments. And you can quickly perform a "Find in files" to learn where this procedure (or variable or whatever) is used in your project.

I do agree, however, that at least the most important procedures must have a documentation of their purpose.

[andyH]

Thanks for the responses, particularly the pointer to 'find in files...' I think that does what I wanted.

Once your documentation has run out of sync it has lost much of its value...

Agreed. I would much rather have a dynamic method than something static.

[MarkMLl]

Thanks for the responses, particularly the pointer to 'find in files...' I think that does what I wanted.

Although the auto-completion can be a pain, and it would be nice to have a "don't match" as well as a "match" filter.

MarkMLl

[marcov]

Peganza has a pascal analyser product. I used it a decade ago for Delphi and it was quite nice to get a feel for a large new codebase.

[andyH]

Peganza has a pascal analyser product.

Windows only, I run linux 

[dbannon]

I always work with a terminal open in my source directory, grep tells me most of what I need to know. Yes, as WP says, various structures can obscure things so you do some interpretation each time but its usually easy.

And its always current.

And I also try to have a few lines of comment for any significant method, the IDE show those comments beautifully !

Davo