Barrapunto

En cuanto al desarrollor el principal y grave problema es el tema de la documentación

El problema es que los programadores somos unos vagos :P Nadie tiene ganas de ponerse a documentar un codigo después de haberse tirado 2 semanas, o 4 meses, o 5 años trabajando en ello, porque sencillamente es un coñazo, pero en cambio a muchos de nosotros nos gusta (y siempre ayuda y mucho!) poner comentarios dentro del código. Es decir, no tenemos inconveniente en documentar al mismo tiempo que programamos pero sí que nos molesta tenerlo que hacer después.
Solución? Pues usar una herramienta del estilo javadoc. No debería ser muy complicado extenderla para que funcionara con el lenguaje C y con la pseudo-OOP (o pseudo-OOD, o lo que sea :P) del gtk/gnome.
Por ejemplo, la gente de php ya tiene la suya propia, el php-doc, y lo estan usando para proyectos como el PEAR desde hace un tiempo ya. Tan solo sería cuestión de seguir una serie de reglas a la hora de poner los comentarios, y una vez terminado el código, se trataría de extraer la documentación con la herramienta.