How to document raised exceptions in Delphi?

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?

Why do you want to know which exceptions might be thrown? It's extremely rare that you should catch exceptions, so the need to know the specific type is similarly rare; meanwhile, you should assume that exceptions could be thrown at almost any point, e.g. range checking, floating point, access violation from nil pointer uses, etc. — Barry Kelly, Jan 28 '11 at 15:52
@Barry: There might be several reasons (1) Maybe I want to catch an exception and throw another one (more appropriate one) (2) I might want to show different error dialogs to the user (or no error dialog depending on the context). I'm not talking about unexpected exceptions like access violations and the kind. — jpfollenius, Jan 31 '11 at 07:38

score 4 · Answer 1 · answered Jan 28 '11 at 16:01

4

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

answered Jan 28 '11 at 16:01

Trinidad

2,756
2
25
43

Not an answer, but +1 for the great links. – Nick Hodges Jan 28 '11 at 21:51

score 1 · Answer 2 · answered Jan 28 '11 at 14:52

1

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.

answered Jan 28 '11 at 14:52

PA.

28,486
9
71
95

What use is this since exceptions are thrown across method boundaries? I mean, what can you do with the knowledge the method A only throws exception E if A calls B which in turn throws F, and then B calls C which throws G and so on! I mean, what useful analysis can you perform with this information? – David Heffernan Jan 28 '11 at 15:05
@David: well you could add exception thrown by `B` to the documentation of `A`. The difference is that you only do this once (when writing `A`) and not every time you use `A`. Unfortunately it seems to be a maintenance nightmare - changing `B`'s exception handling now requires changing the documentation of all functions using `B` - very ugly indeed – jpfollenius Jan 28 '11 at 15:13
1

@smasher you would need a tool to do this and I don't see how such a tool could exist. – David Heffernan Jan 28 '11 at 15:19
Nice to see you are using DelphiCodeToDoc :) – TridenT Jan 28 '11 at 16:07

score 1 · Accepted Answer · edited May 23 '17 at 11:47

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

Ken White · Answer 4 · 2022-09-18T16:22:54.540

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}

Just a tip, Documentation Insight can automatically surround documentation in a region. — Baoquan Zuo, Jan 30 '11 at 09:47

score 1 · Answer 5 · answered Jan 29 '11 at 09:56

1

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

answered Jan 29 '11 at 09:56

Alin Sfetcu

542
6
16

1

Thanks, By its impressive WYSIWYG editor, you don't need to know any XML Documentation syntax and You can naturally and happily write documentation. – Baoquan Zuo Jan 30 '11 at 09:45

score 0 · Answer 6 · answered Jan 29 '11 at 20:38

0

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

answered Jan 29 '11 at 20:38

Turin

129
2
10

How to document raised exceptions in Delphi?

6 Answers6

Linked