rigorously document more complex functions