2 # This file is used to define comment generating interface
4 # Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>
6 # SPDX-License-Identifier: BSD-2-Clause-Patent
16 from Library
.StringUtils
import GetSplitValueList
17 from Library
.DataType
import TAB_SPACE_SPLIT
18 from Library
.DataType
import TAB_INF_GUIDTYPE_VAR
19 from Library
.DataType
import USAGE_ITEM_NOTIFY
20 from Library
.DataType
import ITEM_UNDEFINED
21 from Library
.DataType
import TAB_HEADER_COMMENT
22 from Library
.DataType
import TAB_BINARY_HEADER_COMMENT
23 from Library
.DataType
import TAB_COMMENT_SPLIT
24 from Library
.DataType
import TAB_SPECIAL_COMMENT
25 from Library
.DataType
import END_OF_LINE
26 from Library
.DataType
import TAB_COMMENT_EDK1_SPLIT
27 from Library
.DataType
import TAB_COMMENT_EDK1_START
28 from Library
.DataType
import TAB_COMMENT_EDK1_END
29 from Library
.DataType
import TAB_STAR
30 from Library
.DataType
import TAB_PCD_PROMPT
31 from Library
.UniClassObject
import ConvertSpecialUnicodes
32 from Library
.Misc
import GetLocalValue
33 ## GenTailCommentLines
35 # @param TailCommentLines: the tail comment lines that need to be generated
36 # @param LeadingSpaceNum: the number of leading space needed for non-first
39 def GenTailCommentLines (TailCommentLines
, LeadingSpaceNum
= 0):
40 TailCommentLines
= TailCommentLines
.rstrip(END_OF_LINE
)
41 CommentStr
= TAB_SPACE_SPLIT
*2 + TAB_SPECIAL_COMMENT
+ TAB_SPACE_SPLIT
+ \
42 (END_OF_LINE
+ LeadingSpaceNum
* TAB_SPACE_SPLIT
+ TAB_SPACE_SPLIT
*2 + TAB_SPECIAL_COMMENT
+ \
43 TAB_SPACE_SPLIT
).join(GetSplitValueList(TailCommentLines
, END_OF_LINE
))
49 # @param CommentLines: Generic comment Text, maybe Multiple Lines
51 def GenGenericComment (CommentLines
):
54 CommentLines
= CommentLines
.rstrip(END_OF_LINE
)
55 CommentStr
= TAB_SPECIAL_COMMENT
+ TAB_SPACE_SPLIT
+ (END_OF_LINE
+ TAB_COMMENT_SPLIT
+ TAB_SPACE_SPLIT
).join\
56 (GetSplitValueList(CommentLines
, END_OF_LINE
)) + END_OF_LINE
61 # similar to GenGenericComment but will remove <EOL> at end of comment once,
62 # and for line with only <EOL>, '#\n' will be generated instead of '# \n'
64 # @param CommentLines: Generic comment Text, maybe Multiple Lines
65 # @return CommentStr: Generated comment line
67 def GenGenericCommentF (CommentLines
, NumOfPound
=1, IsPrompt
=False, IsInfLibraryClass
=False):
71 # if comment end with '\n', then remove it to prevent one extra line
74 if CommentLines
.endswith(END_OF_LINE
):
75 CommentLines
= CommentLines
[:-1]
78 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ TAB_SPACE_SPLIT
+ TAB_PCD_PROMPT
+ TAB_SPACE_SPLIT
+ \
79 CommentLines
.replace(END_OF_LINE
, '') + END_OF_LINE
81 CommentLineList
= GetSplitValueList(CommentLines
, END_OF_LINE
)
82 FindLibraryClass
= False
83 for Line
in CommentLineList
:
84 # If this comment is for @libraryclass and it has multiple lines
85 # make sure the second lines align to the first line after @libraryclass as below
87 # ## @libraryclass XYZ FIRST_LINE
90 if IsInfLibraryClass
and Line
.find(u
'@libraryclass ') > -1:
91 FindLibraryClass
= True
93 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ END_OF_LINE
95 if FindLibraryClass
and Line
.find(u
'@libraryclass ') > -1:
96 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ TAB_SPACE_SPLIT
+ Line
+ END_OF_LINE
97 elif FindLibraryClass
:
98 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ TAB_SPACE_SPLIT
* 16 + Line
+ END_OF_LINE
100 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ TAB_SPACE_SPLIT
+ Line
+ END_OF_LINE
105 ## GenHeaderCommentSection
107 # Generate Header comment sections
109 # @param Abstract One line of abstract
110 # @param Description multiple lines of Description
111 # @param Copyright possible multiple copyright lines
112 # @param License possible multiple license lines
114 def GenHeaderCommentSection(Abstract
, Description
, Copyright
, License
, IsBinaryHeader
=False, \
115 CommChar
=TAB_COMMENT_SPLIT
):
119 # Convert special character to (c), (r) and (tm).
121 Abstract
= ConvertSpecialUnicodes(Abstract
)
122 Description
= ConvertSpecialUnicodes(Description
)
124 Content
+= CommChar
* 2 + TAB_SPACE_SPLIT
+ TAB_BINARY_HEADER_COMMENT
+ '\r\n'
125 elif CommChar
== TAB_COMMENT_EDK1_SPLIT
:
126 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ TAB_COMMENT_EDK1_START
+ TAB_STAR
+ TAB_SPACE_SPLIT
+\
127 TAB_HEADER_COMMENT
+ '\r\n'
129 Content
+= CommChar
* 2 + TAB_SPACE_SPLIT
+ TAB_HEADER_COMMENT
+ '\r\n'
131 Abstract
= Abstract
.rstrip('\r\n')
132 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ ('\r\n' + CommChar
+ TAB_SPACE_SPLIT
).join(GetSplitValueList\
134 Content
+= '\r\n' + CommChar
+ '\r\n'
136 Content
+= CommChar
+ '\r\n'
139 Description
= Description
.rstrip('\r\n')
140 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ ('\r\n' + CommChar
+ TAB_SPACE_SPLIT
).join(GetSplitValueList\
142 Content
+= '\r\n' + CommChar
+ '\r\n'
145 # There is no '#\n' line to separate multiple copyright lines in code base
148 Copyright
= Copyright
.rstrip('\r\n')
149 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ ('\r\n' + CommChar
+ TAB_SPACE_SPLIT
).join\
150 (GetSplitValueList(Copyright
, '\n'))
151 Content
+= '\r\n' + CommChar
+ '\r\n'
154 License
= License
.rstrip('\r\n')
155 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ ('\r\n' + CommChar
+ TAB_SPACE_SPLIT
).join(GetSplitValueList\
157 Content
+= '\r\n' + CommChar
+ '\r\n'
159 if CommChar
== TAB_COMMENT_EDK1_SPLIT
:
160 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ TAB_STAR
+ TAB_COMMENT_EDK1_END
+ '\r\n'
162 Content
+= CommChar
* 2 + '\r\n'
167 ## GenInfPcdTailComment
168 # Generate Pcd tail comment for Inf, this would be one line comment
170 # @param Usage: Usage type
171 # @param TailCommentText: Comment text for tail comment
173 def GenInfPcdTailComment (Usage
, TailCommentText
):
174 if (Usage
== ITEM_UNDEFINED
) and (not TailCommentText
):
177 CommentLine
= TAB_SPACE_SPLIT
.join([Usage
, TailCommentText
])
178 return GenTailCommentLines(CommentLine
)
180 ## GenInfProtocolPPITailComment
181 # Generate Protocol/PPI tail comment for Inf
183 # @param Usage: Usage type
184 # @param TailCommentText: Comment text for tail comment
186 def GenInfProtocolPPITailComment (Usage
, Notify
, TailCommentText
):
187 if (not Notify
) and (Usage
== ITEM_UNDEFINED
) and (not TailCommentText
):
191 CommentLine
= USAGE_ITEM_NOTIFY
+ " ## "
195 CommentLine
+= TAB_SPACE_SPLIT
.join([Usage
, TailCommentText
])
196 return GenTailCommentLines(CommentLine
)
198 ## GenInfGuidTailComment
199 # Generate Guid tail comment for Inf
201 # @param Usage: Usage type
202 # @param TailCommentText: Comment text for tail comment
204 def GenInfGuidTailComment (Usage
, GuidTypeList
, VariableName
, TailCommentText
):
205 GuidType
= GuidTypeList
[0]
206 if (Usage
== ITEM_UNDEFINED
) and (GuidType
== ITEM_UNDEFINED
) and \
207 (not TailCommentText
):
210 FirstLine
= Usage
+ " ## " + GuidType
211 if GuidType
== TAB_INF_GUIDTYPE_VAR
:
212 FirstLine
+= ":" + VariableName
214 CommentLine
= TAB_SPACE_SPLIT
.join([FirstLine
, TailCommentText
])
215 return GenTailCommentLines(CommentLine
)
217 ## GenDecGuidTailComment
219 # @param SupModuleList: Supported module type list
221 def GenDecTailComment (SupModuleList
):
222 CommentLine
= TAB_SPACE_SPLIT
.join(SupModuleList
)
223 return GenTailCommentLines(CommentLine
)
227 # get HelpString from a list of HelpTextObject, the priority refer to
230 # @param HelpTextObjList: List of HelpTextObject
232 # @return HelpStr: the help text string found, '' means no help text found
234 def _GetHelpStr(HelpTextObjList
):
236 for HelpObj
in HelpTextObjList
:
237 ValueList
.append((HelpObj
.GetLang(), HelpObj
.GetString()))
238 return GetLocalValue(ValueList
, True)