如何为 hsc2hs 枚举成员制作黑线鳕文档

Question

我正在使用 hsc2hs 从 C header 导入一堆枚举值。我的代码（简化）如下所示：

-- | 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 时，它会为类型 SecurityObjectType 的声明 securityObjectUnknown 和 securityObjectFile 创建空文档块。现在我想要这些的文档。简单地使用

这样的黑线鳕样式注释

-- | 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语法规则。我想要的是将这些评论传播到 auto-generated .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

如何为 hsc2hs 枚举成员制作黑线鳕文档

How to make haddock documentation for hsc2hs enum members

haskell

hsc2hs

haddock