api: document socket
Merge pull request #778 from robszumski/api-socket

api: document socket