Для документирования потока сообщений я обнаружил, что конечные автоматы и диаграммы последовательности имеют свое место. Конечные автоматы лучше описывают решения, которые изменяют состояние системы. Диаграммы последовательности лучше подходят для описания сообщений, которые реализуют определенный элемент протокола.
Поскольку мне все равно нравится использовать Doxygen для внутренней документации, и ему нравится рисовать графики вызовов и другие фигуры с помощью GraphViz tool dot , я начал использовать точку для документирования своих конечных автоматов , Так как Doxygen имеет синтаксис для включения точечного языка непосредственно в исходный код (и даже допускает гиперссылки от элементов чертежа к другим страницам сгенерированной документации), это было действительно удобно. Недавно в Doxygen появилась явная поддержка диаграмм последовательности, выраженных mscgen , что позволяет использовать оба стиля диаграмм.
Наличие цифр, выраженных достаточно естественным образом непосредственно в исходном коде, значительно повышает вероятность их сохранения, чем если бы они были нарисованы внешне в Visio или каком-либо другом инструменте рисования.