How do you guys comment/document your .sql files? Are there conventions similar to those of javadoc and the likes? What is commonly done in large scale database-heavy applications like facebook, twitter, google....
There are no commenting conventions for SQL like Javadoc that I've seen. This would be a great question to pose to the Doxygen people though.
On the other hand, several RDBMS allow this:
COMMENT ON TABLE table_name IS 'This is a comment';
COMMENT ON COLUMN table_name.column_name IS 'This is a great column';
This is more in keeping with the whole RDBMS philosophy - it's all about data. I don't know of any system that will generate nice documentation with this though. Also, I don't think this is standard yet.
I don't think MySQL does comments this way but Oracle and PostgreSQL do.