for the c-docs sure, that's something to look into.
for pike docs the current way has the advantage of working on any class, even stuff that does not exist in files. (consider things like classes in sTeam which are stored in a database, now it makes sense to document them and show the documentation within sTeam.
greetings, martin.