In general, I would love it if every public API view method's docstring included a concrete example of a situation in which the caller is using this for something. I realize you folks already have all this in your head, but it would help me enormously when reviewing.