Проблема с тем же buffer overflow это несовершенство инструментов, а не просто сложность спецификации. Какой бы сложной спецификация не была, программа не должна позволять buffer overflow. Для этого есть rust например. Но йожики будут продолжать писать на C/C++ ведь на C/C++ пишут все. Как впрочем никто не будет ломать обратную совместимость чтобы сделать язык более статически анализируемым.
Я не могу сказать про php, но судя по всему статья в целом для web языков. Так вот, в ruby есть rspec_api_documentation, который прямо по тестам генерирует туже самую документацию. Только при этом она гарантированно синхронизирована с кодовой базой и гарантированно работает (иначе документация просто не соберется). Если для php такого инструмента нет, то стоит его написать вместо траты времени на лишнюю работу в виде декларативного описания апи которое уже описано кодом.
> Elixir похож на Ruby, а Ruby я не знаю совсем
Все понятно.
Т.е написать ту самую либу на гитхабе.
Проблема с тем же buffer overflow это несовершенство инструментов, а не просто сложность спецификации. Какой бы сложной спецификация не была, программа не должна позволять buffer overflow. Для этого есть rust например. Но йожики будут продолжать писать на C/C++ ведь на C/C++ пишут все. Как впрочем никто не будет ломать обратную совместимость чтобы сделать язык более статически анализируемым.