Вот делают всякие-там XML-комментарии.

По-моему это тупо. Вместо этого нужно было сделать
1) специализированный встроенный редактор, например HTML с просмотром
2) навигацию от любого элемента кода к странице, открываемой на редактирование в редакторе документации.

и исходный код бы не замусоривался

и возможностей по редактированию было бы больше, картинки, там с диаграммами видеть в wysiwyg

Вот делают всякие-там XML-комментарии.

По-моему это тупо. Вместо этого нужно было сделать:
1) специализированный встроенный редактор, например HTML с просмотром;
2) навигацию от любого элемента кода к странице, открываемой на редактирование в редакторе документации.

Т исходный код бы не замусоривался

И возможностей по редактированию было бы больше: картинки, например, с диаграммами видеть в wysiwyg.