readd encode-object/encode-slots API with proper documentation

A previous commit removed these generic functions from the API
because of a lack of proper documentation.
We readd them with better documentation, achieved in particular
through the addition of an example showing their use.

Breaking change: ENCODE-SLOTS now has method combination PROGN
as the previous version claimed but did not implement.
Semantically it should not matter, which properties are written first, when encoding to yason, for the reasons you have mentioned. However, when I have to read the encoded object, for exampe while debugging, it feels more natural if the order of the properties reflects the class hierarchy. For example, I would expect key-like properties to be at the top.