+1
Dumping specs may be fine if you have a single clause, but e.g. take a look at specs of erlang:system_flag/2. Then, take a look to the current docs of the function . Basically, everything that utilizes clauses in specs will become very hard to read. Type-specs are for sure way-to-go, but there were situations (in OTP also) in which you don’t improve specs because that would render harder-to-read docs. The point is that specs shouldn’t be removed, but shouldn’t be just dumped either, they should be parsed in order to provide more readable docs.