Но есть одно но - код голый оставлять тоже, не дело.
Кип, ты что-то не туда ушёл )) Документация генерируется как раз на основе комментариев. Поэтому, твой подход закомментировать всё и вся — как нельзя лучше подходит для генератора! Под сырыми исходниками я подразумевал твой закомменченный код, но без тегов yard. Т.е. генератор более-менее понимает и создаёт документацию даже без тегов. Но с тегами всё будет намного лучше. Короче говоря, в теме разработки я покажу как видоизменить комментарии RPG::Actor, чтобы и смысл сохранился и документация получилась правильная.