Документация по функциональному программированию

Question

Есть ли стандартная документация (например, UML для OO) для функциональных языков? После загрузки дивана db, который написан на erlang и смотрящего на исходный код, я был в шоке, вряд ли есть строка документации. Не нужно ли документировать, как все эти функции зависят друг от друга? Существуют ли более хорошо документированные проекты среднего размера, свободно доступные, также учатся, как все это делается с использованием этой парадигмы?

Answer 1

Код должен быть документирован независимо от языка.

Похоже, что есть standard documentation style called EDoc. EDoc может создавать внешнюю документацию API; цитата из одного источника:

EDOC является применение Erlang стандарт документировать Erlang API непосредственно внутри кода Erlang.

Это упоминается в documentation section at erlang.org:

EDOC позволяет писать документацию из программы Erlang в качестве комментариев в сам исходный код, используя теги на форма «@name .. . ". Исходный файл не должен содержать тег для EDOC генерировать документацию, но без тегов результата будет только содержит основную доступную информации, которую можно извлечь из модуля.

A focused Google search доставит вас отсюда.

Answer 2

В таких функциональных языках, как Haskell или ML, которые имеют типы и, возможно, типы модулей (называемые «подписи» в стандартном ML), типы предоставляют очень много документации. В функциональных языках, таких как Scheme, которые не имеют типов, проверенных компилятором, вместо этого они используют «контракты» вместо —, за исключением случаев, когда они неаккуратные.

Erlang был разработан в Эрикссон, и телекоммуникационная индустрия имеет очень сильную культуру и рекордные испытания. Меня не удивило бы, если документация о том, как эти функции должны работать, находится где-то в тестовом наборе.

Резюме: Двумя ближайшими к стандарту являются типы (для функциональных языков с системами статического типа) и контракты (для функциональных языков, не имеющих систем статического типа).

Answer 3

Это очень интересная проблема!

Есть две проблемы: первая комментирует код и записывает некоторую документацию (в текстовой форме). Это должно быть сделано обычным способом, как на языках OO. Вы просто напишите обзор всех модулей, функций и типов, которые вы используете в своем проекте. В F # (функциональный язык для .NET) вы можете писать комментарии XML так же, как в F #, и генерировать документацию из этих комментариев. Я считаю, что F# documentation на MSDN генерируется автоматически из этих комментариев.Вот пример из F # исходный код (если установить F # для VS 2008, он будет также установить исходный код основных библиотек, которые могли бы быть интересный ресурс):

/// Return the first element of the list. 
/// 
/// Raises <c>System.ArgumentException</c> if <c>list</c> is empty 
val head: list:'T list -> 'T 

Вторая вещь, которую вы упомянули, является UML - нет стандарта для построения диаграмм для функциональных языков. Кажется, это сложная проблема. Однако, безусловно, возможно создать диаграмму для кода, который использует определенную библиотеку. Многие функциональные библиотеки позволяют составлять код, составляя несколько простых функций. Обработка списка является хорошим примером:

let custNames = customers |> List.map (fun customer -> customer.Name) 
let empNames = employees |> List.map (fun employee -> employee.Name) 
let result = List.concat [custNames; empNames] 

Это может быть хорошо визуально представлен рисунок потока данных:

+-----------+ +-----+ 
| customers |--->| map |\ 
+-----------+ +-----+ \ +--------+ +--------+ 
          >| concat |-->| result | 
+-----------+ +-----+/+--------+ +--------+ 
| employees |--->| map |/ 
+-----------+ +-----+ 

Подобные рисунки можно сделать для многих функциональных библиотек, и они, кажется, очень полезно (это то, что вы рисуете, когда что-то обсуждаете на доске). Однако, насколько я знаю, нет никаких инструментов для этого автоматически (хотя это должно быть возможно ИМХО).