The GitHub project you looked in for newer definitions is the correct one. If there have not been any more updates than that is because there are none. The alfresco-workflow APIs should be considered "stable", as in "not going to be evolved much" because Alfresco is putting focus on enhancing standalone Activiti 7 / Cloud and Alfresco Process Service, and the embedded workflow engine (alfresco-workflow) is more or less bound to be removed at some point. It has actually been communicated as de-facto deprecated with Alfresco 6.0.
And yes, there are many differences between documentation and actual behaviour. The v1 ReSt API in Alfresco 5.2 was a first development state, and I would argue even now it is far from complete / sufficiently evolved to be considered final or stable. Unfortunately, the development process is not one of "API first", but of "ADF / UI first", so some operations are quite tailored to serving that UI framework instead of being generally useful.