Что значит задокументированная функция?

Вспоминая времена, когда не было никаких версионных git-ов, а к “хабам” программного обеспечения, то есть фондам, были жесткие требования, где библиотеки, ещё не были большими и, фактически, не отличались от модулей, все зависимости функций (или вызывающих процедур, то что сейчас тоже нызывают функциями, возвращающими несколько параметров, а не только “себя“), в описаниях этих функций их зависимости обязательно указывались. И это помимо общего интерфейса и кода тела функции с комментариями. Функция - это та самая программа (план вычислений) или алгоритм и если его код (формальное описание) больше дюжины строк, то комментарии неизбежны, собственно, по этой причине, они и возникли. Кроме того, обязательно указывались требования к компилятору (транслятору). Сейчас это требование стало более общим как метаинформация, хотя скорее всего и этот аспект требует конвенций, какого-то стандартного подхода. Именно об этом я думаю, планируя структуру мануала. Вокруг какой-то концепции, её термина просто собрать все определения, определения переменных (параметров) и определения функций, которые те же параметры (переменные, тем более, если от них требуют первоклассности!).

Таким образом, думая о зависимостях функции lisp, стал внимательнее исследовать, что у нас с nativ и struct … то есть ровно те функции, которые автор рекомендует посмотреть. Но вот насколько эти самые “см. …” адекватны зависимостям. Так вот нет. Авторские связывания в виде рекомендаций “посмотреть” для пользователя не имеют явных параметров такой классификации. Да иногда, интуитивно, можно осознать некоторую связь, но без уверенности, что в данном конкретном случае понимания, обнаружен тот самый параметр, который подразумевал автор, а тем более, что это зависимости, что часто совсем не так.

Вопрос не праздный и я на данный момент не уверен, что мне удасться сконструировать на базе имеющейся информации весь граф зависимостей и собрать вокруг лексем весь код и все описания. Хотелось бы, если не код, который иногда просто огромный, то хотя бы ссылки на него.

С комментариями хорошо справляются ИИ-боты и тоже есть идея привлечь их к разработке мануала, что я уже отмечал.

Но задача не только большая, но и пока и сложная в том смысле, что я не совсем понимаю когда лексема дублируется. То есть когда обозначение и для параметра и для функции, префиксы тут, конечно, спасают, но кроме этой пары параметров для синхронизации в сознании, есть ещё один - определение для компилятора LLVM и определения, собственно, для интерпретатора PicoLisp. То есть, часто определения два … и даже три (и больше!), если учитывать “лексическую семантику“.

И вот я ещё и понял почему лишнии скобки - зло! Да, эта естественный путь описания структуры, особенно иерархической. Но уже ту же сеть, граф, описывают более унверсальным средством - ассоциативным массивом, каким-то там деревьями (кучами), которые, в конечно итоге, все представляются последовательностями пар. Да и суть вычислительного процесса - это не что иное как последовательность импликаций! Вот почему “шитый код” воспринимается лучше! Так и со списками, которые в некотором смысле универсальное средство описание структур, но, скорее для машины, а не для человека.

Отсюда и возникает сомнение по поводу системы PicoLisp, желание увидеть его простую архитектуру (а следовательно и гениальную!) в ASON формате! Поэтому все чаще и чаще возникает вопрос о времени, которое тратится на изучение PicoLisp. Ещё раз акцентирую, что это лучший проект для образования! В нем есть все, что необходимо для понимания программирования в целом, хотя с классами автор перебарщивает и подозрителен в части “слов Forth” и массивов (APL, а тем более, AWK). И, вообще, зачем нам LLVM, когда есть С. И при этом есть LLVM, но нет WASM.

Но буду продолжать исследование, как задумано, в течении всего этого календарного года. Удасться ли найти удобное представление для мануала … будем стараться. А пока определяемся со структурой описания функций (символов) в целом. Общего принципа нам не достаточно! “Собака зарыта в деталях”!