improved internal documentation