annotate all core/ORM generative methods with some standard notation referring to a "generative" glossary entry; specify return value

[foo foo]

http://docs.sqlalchemy.org/ru/latest/core/expression_api.html#sqlalchemy.sql.expression.Insert

The documentation for the values() call isn't clear about what it returns. Apparently it returns a new Insert object, with the provided values arguments associated with it. Connection.excecute() should then be called on this returned value. The passed-in values are not attached, or "fixed" to the insert object itself, but to a new one that values() instantiates and returns.

The documentation isn't clear on this and the examples don't show it being used in this way.

Simply listing the method's return type would be sufficient but adding an additional explanation, or showing this usage in the examples, would be helpful as well.

[Mike Bayer]

ideally every function would have a return type specified at that point, I wouldn't limit this to just insert(). A link to a glossary entry for "generative" should be provided as well.