added docblocks for explicit flow control