Лучший способ документировать код AJAX + PHP?

Я думаю, ваш метод очень хорош. Единственное, что все внутри js файла доступно для чтения другим пользователям, и поэтому документирование того, какие файлы PHP используются, может привести к дыре в безопасности, если они не попадут в файл, который возвращает то, чего не должен. Кроме того, хотя это не имеет большого значения, на сайтах с более высоким трафиком загрузка, скажем, 500 байт комментариев может привести к увеличению.

Оба они не большие, но просто мысли, которые у меня были раньше.

Я считаю, что лучше всего использовать иерархический подход.

Для документации на уровне API, например на уровне функций и классов, напишите встроенную документацию в код и сгенерируйте из них html-документацию, используя множество инструментов документации (JSDoc, phpDocumentor, OraDoclet и т. д.). Бонусные баллы, если ваши инструменты документации могут интегрироваться с вашими инструментами управления версиями, чтобы вы могли переходить к определенным строкам кода из ваших документов api.

Когда у вас есть инструменты для работы с документами, начните создавать документацию как часть процесса сборки (у вас есть процесс сборки, верно?) Для каждой новой сборки и отправляйте документацию в стандартное веб-расположение.

После того, как эти api-документы размещены в сети, вы можете создать вики-страницу для высокоуровневой документации, такой как взаимодействие браузера-> веб-> БД, пользовательские истории, схемы схем и т. д. Для высокоуровневой документации лучше всего писать краткую прозу или маркированный список, при необходимости ссылки на api docs и систему управления версиями.

Обслуживайте свой javascript (и css) через PHP - вы можете хранить свои исходные файлы вместе для облегчения перекрестных ссылок, а при осторожном использовании заголовков вы можете легко справиться с кешированием. Это также позволяет вам иметь красиво отформатированную версию с большим количеством комментариев, которую вы затем можете сжать или скрыть перед отправкой в ​​браузер.

function OutputJs($Content) {
    ob_start();
    echo $Content;
    $expires = DAY_IN_S;
    header("Content-type: x-javascript");
    header('Content-Length: ' . ob_get_length());
    header('Cache-Control: max-age='.$expires.', must-revalidate');
    header('Pragma: public');
    header('Expires: '. gmdate('D, d M Y H:i:s', time()+$expires).'GMT');
    ob_end_flush(); 
}

Для проектов с большим количеством javascript я использую систему сборки (файлы сборки) с минимизатор javascript. Как отмечает автор jsmin, удаление комментариев «способствует более выразительному стилю программирования, поскольку устраняет затраты на загрузку чистой грамотной самодокументации».

Бонус в том, что jsmin также удаляет комментарии из CSS, так что вы также можете свободно комментировать там. (Я считаю, что использование классов css имеет решающее значение для написания чистого javascript.)

Интересная идея использовать PHP для динамического вырезания кода и организации файлов javascript. Имейте в виду, что важная оптимизация для веб-приложений - это уменьшить количество HTTP-запросов, поэтому часто бывает целесообразно объединить меньшие файлы javascript вместе. (Я обнаружил, что простое объединение минимизированных файлов js в один файл отлично работает.)