1

Let's say I have a following function:

int reserve(DmaChannel& channel, const uint8_t request)
{
    const auto ret = channel.reserve(request);
    if (ret != 0)
        return ret;

    channel_ = &channel;
    return 0;
}

It is clearly visible, that the function can fail (when the channel is busy, but this doesn't matter here).

In the doxygen documentation for this function, can I say that it's post-condition is "channel is reserved", assuming that it is logical that the post-condition holds only if the function completed successfully? Or maybe I should think of post-conditions as something that is true in absolutely every possible return from the function, with success value, with error value or with exception?

Generally a post-condition which is valid only if the function is successful can be easily expressed with proposed C++20 contracts like this:

int reserve(DmaChannel& channel, uint8_t request)
[[ ensures ret : channel.isReserved() == true || ret != 0 ]];

However I'm not sure whether my logic is the same as the generally accepted understanding of post-conditions.

Some programmer dude
  • 400,186
  • 35
  • 402
  • 621
Freddie Chopin
  • 8,440
  • 2
  • 28
  • 58
  • 1
    Stepping in the shoes of someone who'll be reading the docs, I would definitely appreciate a clear description of what happens when the function succeeds as well as when it fails, given that side effects differ in these two cases. There's no need to deliberately make the documentation vague and open to guessing. – Violet Giraffe Feb 25 '19 at 13:20
  • While a small part of your question is language-agnostic (the Doxygen part), most of the rest of the question is very C++-specific. Because of that I removed the `c` language tag. – Some programmer dude Feb 25 '19 at 13:22
  • 2
    In my book, when a function returns (as opposed to throws an exception), there cannot be an "unsuccessful function call". Because "success" is in the eye of the beholder. Therefore, you must note the post-conditions for all circumstances under which the function can return. – j6t Feb 25 '19 at 13:58

0 Answers0