How to document raised exceptions in Delphi? [closed]

Question

It happens to me quite often that I call a function Foo and want to know what exceptions this function might throw. In order to find out I then look into the implementation of Foo, but that is not enough. Foo might indeed call a function Bar that raises an exception.

Sometimes I even miss Java's checked exception handling.

So it is obivous to me that it is necessary to document the exceptions each function can throw: the question is: how? Are there any best practices on how to document exceptions? How do you handle this problem?

Answer 1

I think this covers some part of the problem you became aware of

Cleaner, more elegant and wrong

Cleaner, more elegant and harder to recognize

Answer 2

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

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

I'd use XMLDoc for that (there are various questions on XMLDoc her on SO, and here is some documentation from Embarcadero).

Note however that underlying code can also raise exceptions. Depending on the influence you have on libraries, you can or cannot assure those are always the same. A different thing is the OS: depending on where you run, you can get different exceptions.

--jeroen

Answer 3

We use Javadoc style comments for documentation. We extract the info and generate the output with some simple text scripts. We have used DelphiCodeToDoc, too.

Documenting exceptions, we have mandated to use the @throws tag.

Answer 4

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

Answer 5

I use XMLDoc comments. It's basically adding a specialized type of comment to your code in the interface section, just above the property or method declarations. Here's a nonsensical (of course) example. If you add similar style comments in your code, they'll pop up in Code Insight when you invoke it while writing code, just like the VCL's 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}
    constructor 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 collapsed out of the way unless I want to edit them. I've done so above; if you don't like them, remove the lines with {$REGION } and {$ENDREGION}

Answer 6

I use PasDoc for documenting almost all of my Delphi projects. It includes a "raises" tag which does what you seem to be asking for.

Regards - turino