Buried under a sugar coating
Tim Mackinnon and I recently did a pair programming session to redesign the guts of the Java Dynamic Mock Objects implementation. One outcome of the session was a lot of methods that provided convenient "syntactic sugar" for setting up common expectations. Those sugar methods just delegated to lower level methods that let you define any kind of expectation in a long winded but extensible manner.
Unfortunately we forgot to make the lower level methods public. The flexible, extensible core was inaccessible to users of the API, who soon started asking awkward questions on the mailing list.
Memo to self: syntactic sugar is layered above an API as a sweetener. Implement the powerful, low level API first. Any kind of sugary syntax can be implemented afterwards.