I tend to think of this sort of thing as a developer comment, for people writing SoCo, rather than for end users of the library.  So I wouldn't normally put it in a doctoring.  What do you think?