update to the inline documentation, hopefully will make things more clear