En mi caso, mi estilo siempre había sido colocar al principio del archivo y antes de la función el nombre de éste/a y una pequeña descripción de lo que te vas a encontrar en él/ella. Pero normalmente la descripción de las funciones se me quedaba un poco corta, hay que aclarar que suelo programar en C, así que decidí pasarme a la sintaxis de JavaDoc que ya la conocía de mi PFC (que hice en Java).

Lo malo es que al programar en C, lo único que me vale de JavaDoc es su sintaxis, ya que la generación de la documentación de la API no la puedo realizar. Así que busqué, y encontré Doxygen (lo usan en KDE), pero la verdad es que lo he probado un poco y no me acaba de convencer, lo bueno es que puedo mantener la sintaxis de JavaDoc, pero la documentación que genera no me gusta.

Así que os pregunto, ¿usáis algún tipo de sintaxis especial para los comentarios? Si es así, ¿cuál? y ¿por qué? Y para terminar, ¿usáis alguna herramienta de generación de documentación a partir de los comentarios? Si es así, ¿cuál? y ¿por qué?

Resulta que para un programa en C (sobre Linux) necesito calcular los hashes del contenido de varios ficheros, y buscando por todos sitios no encuentro ninguna librería que realice dicha operación. Lo máximo que he encontrado ha sido el algoritmo de los SHA (que son los que me interesan) para luego programarlo y las GNU Core Utilities que tienen un algoritmo en C para SHA, pero que me da un poco de rabia copiar y pegar sin entenderlo, así que prefiero la solución de una librería que me proporcione las funciones necesarias para realizar dichos hashes.

¿Alguién tiene alguna idea o conoce algo así?