improves documentation, fixes various bugs, improves objects returned by promises