BaseTools/Source/Python/UPT/Library/CommentGenerating.py

   1 ## @file
   2 # This file is used to define comment generating interface
   3 #
   4 # Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   5 #
   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
  10 #
  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.
  13 #
  14
  15 '''
  16 CommentGenerating
  17 '''
  18
  19 ##
  20 # Import Modules
  21 #
  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 LANGUAGE_EN_US
  28
  29 ## GenTailCommentLines
  30 #
  31 # @param TailCommentLines:  the tail comment lines that need to be generated
  32 # @param LeadingSpaceNum:   the number of leading space needed for non-first
  33 #                            line tail comment
  34 #
  35 def GenTailCommentLines (TailCommentLines, LeadingSpaceNum = 0):
  36     EndOfLine = "\n"
  37     TailCommentLines = TailCommentLines.rstrip(EndOfLine)
  38     CommentStr = "  ## " + (EndOfLine + LeadingSpaceNum * TAB_SPACE_SPLIT + \
  39                             "  ## ").join(GetSplitValueList(TailCommentLines, \
  40                                                             EndOfLine))
  41     return CommentStr
  42
  43 ## GenGenericComment
  44 #
  45 # @param CommentLines:   Generic comment Text, maybe Multiple Lines
  46 #
  47 def GenGenericComment (CommentLines):
  48     if not CommentLines:
  49         return ''
  50     EndOfLine = "\n"
  51     CommentLines = CommentLines.rstrip(EndOfLine)
  52     CommentStr = '## ' + (EndOfLine + '# ').join\
  53     (GetSplitValueList(CommentLines, EndOfLine)) + EndOfLine
  54     return CommentStr
  55
  56 ## GenGenericCommentF
  57 #
  58 #  similar to GenGenericComment but will remove <EOL> at end of comment once,
  59 #  and for line with only <EOL>, '#\n' will be generated instead of '# \n'
  60 #
  61 # @param CommentLines:   Generic comment Text, maybe Multiple Lines
  62 # @return CommentStr:    Generated comment line
  63 #
  64 def GenGenericCommentF (CommentLines, NumOfPound=1):
  65     if not CommentLines:
  66         return ''
  67     EndOfLine = "\n"
  68     #
  69     # if comment end with '\n', then remove it to prevent one extra line
  70     # generate later on
  71     #
  72     if CommentLines.endswith(EndOfLine):
  73         CommentLines = CommentLines[:-1]
  74     CommentLineList = GetSplitValueList(CommentLines, EndOfLine)
  75     CommentStr = ''
  76     for Line in CommentLineList:
  77         if Line == '':
  78             CommentStr += '#' * NumOfPound + '\n'
  79         else:
  80             CommentStr += '#' * NumOfPound + ' ' + Line + '\n'
  81
  82     return CommentStr
  83
  84
  85 ## GenHeaderCommentSection
  86 #
  87 # Generate Header comment sections
  88 #
  89 # @param Abstract      One line of abstract
  90 # @param Description   multiple lines of Description
  91 # @param Copyright     possible multiple copyright lines
  92 # @param License       possible multiple license lines
  93 #
  94 def GenHeaderCommentSection(Abstract, Description, Copyright, License):
  95     EndOfLine = '\n'
  96     Content = ''
  97
  98     Content += '## @file' + EndOfLine
  99     if Abstract:
 100         Abstract = Abstract.rstrip(EndOfLine)
 101         Content += '# ' + Abstract + EndOfLine
 102         Content += '#' + EndOfLine
 103     else:
 104         Content += '#' + EndOfLine
 105
 106     if Description:
 107         Description = Description.rstrip(EndOfLine)
 108         Content += '# ' + (EndOfLine + '# ').join(GetSplitValueList\
 109                                                   (Description, '\n'))
 110         Content += EndOfLine + '#' + EndOfLine
 111
 112     #
 113     # There is no '#\n' line to separate multiple copyright lines in code base
 114     #
 115     if Copyright:
 116         Copyright = Copyright.rstrip(EndOfLine)
 117         Content += '# ' + (EndOfLine + '# ').join\
 118         (GetSplitValueList(Copyright, '\n'))
 119         Content += EndOfLine + '#' + EndOfLine
 120
 121     if License:
 122         License = License.rstrip(EndOfLine)
 123         Content += '# ' + (EndOfLine + '# ').join(GetSplitValueList\
 124                                                   (License, '\n'))
 125         Content += EndOfLine + '#' + EndOfLine
 126
 127     Content += '##' + EndOfLine
 128
 129     return Content
 130
 131
 132 ## GenInfPcdTailComment
 133 #  Generate Pcd tail comment for Inf, this would be one line comment
 134 #
 135 # @param Usage:            Usage type
 136 # @param TailCommentText:  Comment text for tail comment
 137 #
 138 def GenInfPcdTailComment (Usage, TailCommentText):
 139     if (Usage == ITEM_UNDEFINED) and (not TailCommentText):
 140         return ''
 141
 142     CommentLine = TAB_SPACE_SPLIT.join([Usage, TailCommentText])
 143     return GenTailCommentLines(CommentLine)
 144
 145 ## GenInfProtocolPPITailComment
 146 #  Generate Protocol/PPI tail comment for Inf
 147 #
 148 # @param Usage:            Usage type
 149 # @param TailCommentText:  Comment text for tail comment
 150 #
 151 def GenInfProtocolPPITailComment (Usage, Notify, TailCommentText):
 152     if (not Notify) and (Usage == ITEM_UNDEFINED) and (not TailCommentText):
 153         return ''
 154
 155     if Notify:
 156         CommentLine = USAGE_ITEM_NOTIFY + " ## "
 157     else:
 158         CommentLine = ''
 159
 160     CommentLine += TAB_SPACE_SPLIT.join([Usage, TailCommentText])
 161     return GenTailCommentLines(CommentLine)
 162
 163 ## GenInfGuidTailComment
 164 #  Generate Guid tail comment for Inf
 165 #
 166 # @param Usage:            Usage type
 167 # @param TailCommentText:  Comment text for tail comment
 168 #
 169 def GenInfGuidTailComment (Usage, GuidTypeList, VariableName, TailCommentText):
 170     GuidType = GuidTypeList[0]
 171     if (Usage == ITEM_UNDEFINED) and (GuidType == ITEM_UNDEFINED) and \
 172         (not TailCommentText):
 173         return ''
 174
 175     FirstLine = Usage + " ## " + GuidType
 176     if GuidType == TAB_INF_GUIDTYPE_VAR:
 177         FirstLine += ":" + VariableName
 178
 179     CommentLine = TAB_SPACE_SPLIT.join([FirstLine, TailCommentText])
 180     return GenTailCommentLines(CommentLine)
 181
 182 ## GenDecGuidTailComment
 183 #
 184 # @param SupModuleList:  Supported module type list
 185 #
 186 def GenDecTailComment (SupModuleList):
 187     CommentLine = TAB_SPACE_SPLIT.join(SupModuleList)
 188     return GenTailCommentLines(CommentLine)
 189
 190
 191 ## _GetHelpStr
 192 #  get HelpString from a list of HelpTextObject, the priority refer to
 193 #  related HLD
 194 #
 195 #  @param HelpTextObjList: List of HelpTextObject
 196 #
 197 #  @return HelpStr: the help text string found, '' means no help text found
 198 #
 199 def _GetHelpStr(HelpTextObjList):
 200     HelpStr = ''
 201
 202     for HelpObj in HelpTextObjList:
 203         if HelpObj and HelpObj.GetLang() == LANGUAGE_EN_US:
 204             HelpStr = HelpObj.GetString()
 205             return HelpStr
 206
 207     for HelpObj in HelpTextObjList:
 208         if HelpObj and HelpObj.GetLang().startswith('en'):
 209             HelpStr = HelpObj.GetString()
 210             return HelpStr
 211
 212     for HelpObj in HelpTextObjList:
 213         if HelpObj and not HelpObj.GetLang():
 214             HelpStr = HelpObj.GetString()
 215             return HelpStr
 216
 217     return HelpStr