Separate hand written specification is rulez for human. It is best short module description (with some useful manually written comments). I like it more then autogenerated docs (by doxygen and so on).
Autogenerated specifications (headers and so on) are worst and ugly. But in language like java and C# it is last chance if there is no autogenerated docs and sources.
