Как сделать документацию по пикше для членов перечисления hsc2hs

Question

Я использую hsc2hs для импорта набора значений enum из заголовка C. Мой код (упрощенный) выглядит так:

-- | newtype wrapper around Windows SDK SE_OBJECT_TYPE enumeration
newtype SecurityObjectType = SecurityObjectType BYTE
#{enum SecurityObjectType, SecurityObjectType
 , securityObjectUnknown            = SE_UNKNOWN_OBJECT_TYPE
 , securityObjectFile               = SE_FILE_OBJECT
 }

Когда я бегу cabal haddock в моем проекте он создает пустые блоки документации для объявлений securityObjectUnknown а также securityObjectFile типа SecurityObjectType, Теперь я хотел бы иметь документацию для них. Просто используя комментарии в стиле пикши, такие как

-- | newtype wrapper around Windows SDK SE_OBJECT_TYPE enumeration
newtype SecurityObjectType = SecurityObjectType BYTE
#{enum SecurityObjectType, SecurityObjectType
 -- | Unknown object type
 , securityObjectUnknown            = SE_UNKNOWN_OBJECT_TYPE
 -- | Indicates a file or directory. The name string that identifies a file
 -- or directory object can be in one of the following formats:
 --  * A relative path, such as FileName.dat or ..\FileName
 --  * An absolute path, such as FileName.dat, C:\DirectoryName\FileName.dat,
 --    or G:\RemoteDirectoryName\FileName.dat.
 --  * A UNC name, such as \\ComputerName\ShareName\FileName.dat.
 , securityObjectFile               = SE_FILE_OBJECT
 }

мешает работе hsc2hs и приводит к сбою сборки. Но я хочу, чтобы эти декларации были задокументированы. Как я мог это сделать?

UPD: Вот сообщение об ошибке, сгенерированное во время сборки, если у меня есть комментарии:

Preprocessing library Win32-security-0.1...                                                                                     
SecurityInfo.hsc: In function 'main':                                                                                           
SecurityInfo.hsc:47:5: error: lvalue required as decrement operand                                                              
SecurityInfo.hsc:47:5: error: 'Indicates' undeclared (first use in this function)                                               
SecurityInfo.hsc:47:5: note: each undeclared identifier is reported only once for each function it appears in                   
SecurityInfo.hsc:47:5: error: expected ')' before 'a'                                                                           
SecurityInfo.hsc:47:5: error: lvalue required as decrement operand                                                              
SecurityInfo.hsc:47:5: error: expected ')' before 'a'                                                                           
SecurityInfo.hsc:47:5: error: lvalue required as decrement operand                                                              
SecurityInfo.hsc:47:5: error: expected ')' before 'a'                                                                           
SecurityInfo.hsc:55:20: warning: missing terminating " character                                                                
SecurityInfo.hsc:56:24: warning: missing terminating " character                                                                
SecurityInfo.hsc:66:20: warning: missing terminating " character                                                                
SecurityInfo.hsc:67:18: warning: missing terminating " character                                                                
SecurityInfo.hsc:71:20: warning: missing terminating " character                                                                
SecurityInfo.hsc:72:2: warning: missing terminating " character                                                                 
SecurityInfo.hsc:237:0: error: unterminated argument list invoking macro "hsc_enum"                                             
SecurityInfo.hsc:53:5: error: 'hsc_enum' undeclared (first use in this function)                                                
SecurityInfo.hsc:53:5: error: expected ';' at end of input                                                                      
SecurityInfo.hsc:53:5: error: expected declaration or statement at end of input                                                 
compiling dist\build\System\Win32\Security\SecurityInfo_hsc_make.c failed (exit code 1)                 

Номера строк на самом деле не совпадают, потому что пример упрощен, но строка 47 в выводе ошибок соответствует -- | Unknown object type линия.

Копаться в сгенерирован SecurityInfo_hsc_make.c файл ясно показывает проблему (вот фрагмент):

#line 47 "SecurityInfo.hsc"
    hsc_enum (SecurityObjectType,  SecurityObjectType
 -- | Unknown object type
 , hsc_printf ("%s", "securityObjectUnknown            "),  SE_UNKNOWN_OBJECT_TYPE
 -- | Indicates a file or directory. The name string that identifies a file
 -- or directory object can be in one of the following formats:
 --  * A relative path);
    hsc_enum (SecurityObjectType,  SecurityObjectType
 -- | Unknown object type
 , hsc_haskellize ("such as FileName.dat or ..\FileName
 --  * An absolute path"), such as FileName.dat or ..\FileName
 --  * An absolute path);
    hsc_enum (SecurityObjectType,  SecurityObjectType
 -- | Unknown object type
 , hsc_haskellize ("such as FileName.dat"), such as FileName.dat);
    hsc_enum (SecurityObjectType,  SecurityObjectType
 -- | Unknown object type

Комментарии на Haskell просто вставляются в сгенерированный C-файл, что явно нарушает правила синтаксиса C. Я хотел, чтобы эти комментарии распространялись на автоматически сгенерированные .hs файл.

Answer 1

Насколько я могу судить, вы должны определить каждое значение по одному, используя #const вместо того, чтобы определять их сразу #enum если вы хотите добавить документацию.

-- | Unknown object type
securityObjectUnknown :: SecurityObjectType
securityObjectUnknown = SecurityObjectType #const SE_UNKNOWN_OBJECT_TYPE

-- | Indicates a file or directory. The name string that identifies a file
-- or directory object can be in one of the following formats:
--  * A relative path, such as FileName.dat or ..\FileName
--  * An absolute path, such as FileName.dat, C:\DirectoryName\FileName.dat,
--    or G:\RemoteDirectoryName\FileName.dat.
--  * A UNC name, such as \\ComputerName\ShareName\FileName.dat.
securityObjectFile :: SecurityObjectType
securityObjectFile = SecurityObjectType #const SE_FILE_OBJECT