How to document raised exceptions in Delphi?

Question

It often happens to me that I call the Foo function and want to know what exceptions this function may throw. To find out, I look into the implementation of Foo , but this is not enough. Foo can actually call the Bar function, which throws an exception.

Sometimes I even skip handling Java excluded.

So it went to me that it is necessary to document the exceptions that each function may throw: the question is: how? Are there any guidelines for documenting exceptions? How do you deal with this problem?

Answer 1

Most Delphi applications are VCL applications. They do not require a checked exception, because the main message loop has a try / except block that catches everything.

It may be good practice to document which exceptions may be explicitly raised by your code.

I would use XMLDoc for this (there are various questions on its XMLDoc on SO, and here is some documentation from Embarcadero ).

Please note, however, that the underlying code may also throw exceptions. Depending on the influence you have in the libraries, you may or may not guarantee that they are always the same. The OS is another matter: depending on where you work, you may receive different exceptions.

- Jeroen

Answer 2

I think this applies to some part of the problem that you learned about.

Cleaner, more elegant and wrong

Cleaner, more elegant and harder to recognize

Answer 3

We use Javadoc style comments for documentation. We extract information and generate output using some simple text scripts. We also used DelphiCodeToDoc.

By documenting exceptions, we committed to using the @throws tag.

Answer 4

this is great for documenting code - Insight Documentation from DevJet.net

Answer 5

I use XMLDoc comments (see links and discussion here . This is basically adding a specialized type of comment to your code in the section of the interface, simply over declarations of properties or methods. Thus, a senseless (of course) example. If you add similar style comments to your code, they will appear in Code Insight when you call it when writing code, as the VCL documentation does.

 type {$REGION 'TMyClass description'} /// <summary>TMyClass is a descendent of TComponent /// which performs some function.</summary> {$ENDREGION} TMyClass=class(TComponent) private // your private stuff FSomeProp: Boolean; procedure SetSomeProp(Value: Boolean); protected // your protected stuff public {$REGION 'TMyClass constructor'} /// <summary> TMyClass constructor.</summary> /// <remarks>Creates an instance of TMyClass.</remarks> /// <param>Owner: TObject. The owner of the instance of TMyClass</param> /// <exception>Raises EMyObjectFailedAlloc if the constructor dies /// </exception> {$ENDREGION} Create(Owner: TObject); override; published {$REGION 'TMyClass.Someprop'} /// <summary>Someprop property</summary> /// <remarks>Someprop is a Boolean property. When True, the /// thingamajig automatically frobs the widget. Changing this /// property also affects the behavior of SomeOtherProp.</remarks> {$ENDREGION} property Someprop: Boolean read FSomeProp write SetSomeProp; end; 

I prefer to wrap these XMLDoc comments in regions, so they can be minimized out of the way if I don't want to edit them. I have done it above; if you don’t like it, delete the lines using {$ REGION} and {$ ENDREGION}

Answer 6

I use PasDoc to document almost all of my Delphi projects. It includes “raise” tags that do what you seem to be asking for.

Relationships - turino