more documentation on edge cases