2 # This file is used to define comment generating interface
4 # Copyright (c) 2011 - 2014, Intel Corporation. All rights reserved.<BR>
6 # This program and the accompanying materials are licensed and made available
7 # under the terms and conditions of the BSD License which accompanies this
8 # distribution. The full text of the license may be found at
9 # http://opensource.org/licenses/bsd-license.php
11 # THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 # WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
22 from Library
.String
import GetSplitValueList
23 from Library
.DataType
import TAB_SPACE_SPLIT
24 from Library
.DataType
import TAB_INF_GUIDTYPE_VAR
25 from Library
.DataType
import USAGE_ITEM_NOTIFY
26 from Library
.DataType
import ITEM_UNDEFINED
27 from Library
.DataType
import TAB_HEADER_COMMENT
28 from Library
.DataType
import TAB_BINARY_HEADER_COMMENT
29 from Library
.DataType
import TAB_COMMENT_SPLIT
30 from Library
.DataType
import TAB_SPECIAL_COMMENT
31 from Library
.DataType
import END_OF_LINE
32 from Library
.DataType
import TAB_COMMENT_EDK1_SPLIT
33 from Library
.DataType
import TAB_COMMENT_EDK1_START
34 from Library
.DataType
import TAB_COMMENT_EDK1_END
35 from Library
.DataType
import TAB_STAR
36 from Library
.DataType
import TAB_PCD_PROMPT
37 from Library
.UniClassObject
import ConvertSpecialUnicodes
38 from Library
.Misc
import GetLocalValue
39 ## GenTailCommentLines
41 # @param TailCommentLines: the tail comment lines that need to be generated
42 # @param LeadingSpaceNum: the number of leading space needed for non-first
45 def GenTailCommentLines (TailCommentLines
, LeadingSpaceNum
= 0):
46 TailCommentLines
= TailCommentLines
.rstrip(END_OF_LINE
)
47 CommentStr
= TAB_SPACE_SPLIT
*2 + TAB_SPECIAL_COMMENT
+ TAB_SPACE_SPLIT
+ \
48 (END_OF_LINE
+ LeadingSpaceNum
* TAB_SPACE_SPLIT
+ TAB_SPACE_SPLIT
*2 + TAB_SPECIAL_COMMENT
+ \
49 TAB_SPACE_SPLIT
).join(GetSplitValueList(TailCommentLines
, END_OF_LINE
))
55 # @param CommentLines: Generic comment Text, maybe Multiple Lines
57 def GenGenericComment (CommentLines
):
60 CommentLines
= CommentLines
.rstrip(END_OF_LINE
)
61 CommentStr
= TAB_SPECIAL_COMMENT
+ TAB_SPACE_SPLIT
+ (END_OF_LINE
+ TAB_COMMENT_SPLIT
+ TAB_SPACE_SPLIT
).join\
62 (GetSplitValueList(CommentLines
, END_OF_LINE
)) + END_OF_LINE
67 # similar to GenGenericComment but will remove <EOL> at end of comment once,
68 # and for line with only <EOL>, '#\n' will be generated instead of '# \n'
70 # @param CommentLines: Generic comment Text, maybe Multiple Lines
71 # @return CommentStr: Generated comment line
73 def GenGenericCommentF (CommentLines
, NumOfPound
=1, IsPrompt
=False, IsInfLibraryClass
=False):
77 # if comment end with '\n', then remove it to prevent one extra line
80 if CommentLines
.endswith(END_OF_LINE
):
81 CommentLines
= CommentLines
[:-1]
84 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ TAB_SPACE_SPLIT
+ TAB_PCD_PROMPT
+ TAB_SPACE_SPLIT
+ \
85 CommentLines
.replace(END_OF_LINE
, '') + END_OF_LINE
87 CommentLineList
= GetSplitValueList(CommentLines
, END_OF_LINE
)
88 FindLibraryClass
= False
89 for Line
in CommentLineList
:
90 # If this comment is for @libraryclass and it has multiple lines
91 # make sure the second lines align to the first line after @libraryclass as below
93 # ## @libraryclass XYZ FIRST_LINE
96 if IsInfLibraryClass
and Line
.find(u
'@libraryclass ') > -1:
97 FindLibraryClass
= True
99 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ END_OF_LINE
101 if FindLibraryClass
and Line
.find(u
'@libraryclass ') > -1:
102 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ TAB_SPACE_SPLIT
+ Line
+ END_OF_LINE
103 elif FindLibraryClass
:
104 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ TAB_SPACE_SPLIT
* 16 + Line
+ END_OF_LINE
106 CommentStr
+= TAB_COMMENT_SPLIT
* NumOfPound
+ TAB_SPACE_SPLIT
+ Line
+ END_OF_LINE
111 ## GenHeaderCommentSection
113 # Generate Header comment sections
115 # @param Abstract One line of abstract
116 # @param Description multiple lines of Description
117 # @param Copyright possible multiple copyright lines
118 # @param License possible multiple license lines
120 def GenHeaderCommentSection(Abstract
, Description
, Copyright
, License
, IsBinaryHeader
=False, \
121 CommChar
=TAB_COMMENT_SPLIT
):
125 # Convert special character to (c), (r) and (tm).
127 if isinstance(Abstract
, unicode):
128 Abstract
= ConvertSpecialUnicodes(Abstract
)
129 if isinstance(Description
, unicode):
130 Description
= ConvertSpecialUnicodes(Description
)
132 Content
+= CommChar
* 2 + TAB_SPACE_SPLIT
+ TAB_BINARY_HEADER_COMMENT
+ '\r\n'
133 elif CommChar
== TAB_COMMENT_EDK1_SPLIT
:
134 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ TAB_COMMENT_EDK1_START
+ TAB_STAR
+ TAB_SPACE_SPLIT
+\
135 TAB_HEADER_COMMENT
+ '\r\n'
137 Content
+= CommChar
* 2 + TAB_SPACE_SPLIT
+ TAB_HEADER_COMMENT
+ '\r\n'
139 Abstract
= Abstract
.rstrip('\r\n')
140 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ ('\r\n' + CommChar
+ TAB_SPACE_SPLIT
).join(GetSplitValueList\
142 Content
+= '\r\n' + CommChar
+ '\r\n'
144 Content
+= CommChar
+ '\r\n'
147 Description
= Description
.rstrip('\r\n')
148 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ ('\r\n' + CommChar
+ TAB_SPACE_SPLIT
).join(GetSplitValueList\
150 Content
+= '\r\n' + CommChar
+ '\r\n'
153 # There is no '#\n' line to separate multiple copyright lines in code base
156 Copyright
= Copyright
.rstrip('\r\n')
157 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ ('\r\n' + CommChar
+ TAB_SPACE_SPLIT
).join\
158 (GetSplitValueList(Copyright
, '\n'))
159 Content
+= '\r\n' + CommChar
+ '\r\n'
162 License
= License
.rstrip('\r\n')
163 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ ('\r\n' + CommChar
+ TAB_SPACE_SPLIT
).join(GetSplitValueList\
165 Content
+= '\r\n' + CommChar
+ '\r\n'
167 if CommChar
== TAB_COMMENT_EDK1_SPLIT
:
168 Content
+= CommChar
+ TAB_SPACE_SPLIT
+ TAB_STAR
+ TAB_COMMENT_EDK1_END
+ '\r\n'
170 Content
+= CommChar
* 2 + '\r\n'
175 ## GenInfPcdTailComment
176 # Generate Pcd tail comment for Inf, this would be one line comment
178 # @param Usage: Usage type
179 # @param TailCommentText: Comment text for tail comment
181 def GenInfPcdTailComment (Usage
, TailCommentText
):
182 if (Usage
== ITEM_UNDEFINED
) and (not TailCommentText
):
185 CommentLine
= TAB_SPACE_SPLIT
.join([Usage
, TailCommentText
])
186 return GenTailCommentLines(CommentLine
)
188 ## GenInfProtocolPPITailComment
189 # Generate Protocol/PPI tail comment for Inf
191 # @param Usage: Usage type
192 # @param TailCommentText: Comment text for tail comment
194 def GenInfProtocolPPITailComment (Usage
, Notify
, TailCommentText
):
195 if (not Notify
) and (Usage
== ITEM_UNDEFINED
) and (not TailCommentText
):
199 CommentLine
= USAGE_ITEM_NOTIFY
+ " ## "
203 CommentLine
+= TAB_SPACE_SPLIT
.join([Usage
, TailCommentText
])
204 return GenTailCommentLines(CommentLine
)
206 ## GenInfGuidTailComment
207 # Generate Guid tail comment for Inf
209 # @param Usage: Usage type
210 # @param TailCommentText: Comment text for tail comment
212 def GenInfGuidTailComment (Usage
, GuidTypeList
, VariableName
, TailCommentText
):
213 GuidType
= GuidTypeList
[0]
214 if (Usage
== ITEM_UNDEFINED
) and (GuidType
== ITEM_UNDEFINED
) and \
215 (not TailCommentText
):
218 FirstLine
= Usage
+ " ## " + GuidType
219 if GuidType
== TAB_INF_GUIDTYPE_VAR
:
220 FirstLine
+= ":" + VariableName
222 CommentLine
= TAB_SPACE_SPLIT
.join([FirstLine
, TailCommentText
])
223 return GenTailCommentLines(CommentLine
)
225 ## GenDecGuidTailComment
227 # @param SupModuleList: Supported module type list
229 def GenDecTailComment (SupModuleList
):
230 CommentLine
= TAB_SPACE_SPLIT
.join(SupModuleList
)
231 return GenTailCommentLines(CommentLine
)
235 # get HelpString from a list of HelpTextObject, the priority refer to
238 # @param HelpTextObjList: List of HelpTextObject
240 # @return HelpStr: the help text string found, '' means no help text found
242 def _GetHelpStr(HelpTextObjList
):
244 for HelpObj
in HelpTextObjList
:
245 ValueList
.append((HelpObj
.GetLang(), HelpObj
.GetString()))
246 return GetLocalValue(ValueList
, True)