'#Uses "..\classes\FunctionClass.cls"
'#Uses "..\classes\ParameterClass.cls"
'#Uses "Const.inc"
Option Explicit
'*****************************************************************************
' Module:
'        Format.inc
'-----------------------------------------------------------------------------
' Description:
'        This module contains constants and global functions that can 
'        be used to format text outputs. This file should be the same
'        for all controllers.
'
'-----------------------------------------------------------------------------
' History:
'                 
'        Rev. Author         Date        Description
'        ----------------------------------------------------------------------
'        1.0  ste            01.02.00    final version
'        1.1  ste            07.03.00    function "FormatParameterTooltip" added         
'
'*****************************************************************************

'*****************************************************************************
' Local Constants
'*****************************************************************************

' Prefix for function description in generated source files
Const MODULE_PREFIX_FIRST_LINE = "// @Description   "
Const MODULE_PREFIX_NEXT_LINE =  "//                "

' Prefix for the tooltips
Const TOOLTIP_PREFIX_FIRST_LINE = "- "
      ' the tooltip is in rtf font so two spaces "  " have
      ' the same wight as one "-"
Const TOOLTIP_PREFIX_NEXT_LINE =  "   "

' comments only in the generated source code
Const COMMENT_FOR_SOURCE_ONLY = "//"
' comment which was show in the generated source code and in the documentation file too
Const COMMENT_FOR_SOURCE_AND_DOCU = "///"
' comment which was show in the documentation file (as warning) too
Const COMMENT_FOR_WARNINGS = "////"

' character for the border from the section header
Const CHARACTER_BORDER_SECTIONS = "-"

' character for the border inside the function/macro headers
Const CHARACTER_INSIDE_FUNCTION_HEADER = "-"
' character for the border outside the function/macro headers
Const CHARACTER_OUTSIDE_FUNCTION_HEADER = "*"

Const MAX_CHARACTERS_FOR_SOURCE = 78
Const MAX_CHARACTERS_FOR_TOOLTIPS = 60
Const MAX_CHARACTERS_FOR_MSG_TEXT = 60


'*****************************************************************************
' Global Functions
'*****************************************************************************

'*****************************************************************************
'Description:
'        This function formats a character string. The Character string is 
'        formatted as a block with leading blanks. The first line can 
'        contain a prefix. The second and all following lines can also 
'        contain a prefix. The maximum length of a line is configurable.
'
'        Example 1:
'            FormatText(2, "- ", "  ", "This is the output text for the 
'                                       first example", 20)
'
'            |  - This is the     
'            |    output text
'            |    for the first
'            |    example
'
'        Example 2:
'            FormatText(0, "", "", "This is the output text for the 
'                                   second example !", 40)
'
'            |This is the output text for the second 
'            |example !  
'
'-----------------------------------------------------------------------------
'Parameters:
'        NumberOfSpaces   number of leading blanks
'        FirstPrefix      prefix for the first line
'        NextPrefix       prefix for the following lines
'        v                character string
'        MaxCharacters    max characters in a line
'-----------------------------------------------------------------------------
'Returns:
'        formatted character string
'*****************************************************************************
Function FormatText(NumberOfSpaces As Integer, FirstPrefix As String, NextPrefix As String, v As String, MaxCharacters As Integer) As String
On Error Goto FormatTextError

  Dim Help As String
  Dim Output As String
  Dim LeftCharacters As String
  Dim Position As Integer
  Dim OldPosition As Integer

  Output = ""
  ' only if the number of the leading blanks plus the number of the signs in 
  ' the prefix for the first line small ones is as the parameter MaxCharacters
  If ((NumberOfSpaces + Len(FirstPrefix)) < MaxCharacters) Then
    ' make a character string with the number of leading blanks, the prefix 
    ' for the first line (FirstPrefix) and the delivered text (v)
    Help = Space(NumberOfSpaces) & FirstPrefix & v

    ' only if the number of characters in the variable Help is larger than 
    ' the parameter MaxCharacters
    If (Len(Help) > MaxCharacters) Then

      ' only if the number of the leading blanks plus the number of the signs in 
      ' the prefix for the next lines small ones is as the parameter MaxCharacters
      If ((NumberOfSpaces + Len(NextPrefix)) < MaxCharacters) Then
        Do
          '--------------------------------------------------------------------------
          ' search the position of last space in the first MaxCharacters characters
          ' beginning with the search after the first space in the variable Help
          '--------------------------------------------------------------------------
          Position = InStr(NumberOfSpaces + Len(NextPrefix) + 1, Help, " ")  ' search for the first space

          ' if the last word is greater then MaxCharacters
          If (Position = 0) Then
            Output = Output & Help
            Exit Do
          Else

            ' if the found position is larger than the parameter MaxCharacters => one word is larger than MaxCharacters 
            If (Position > MaxCharacters) Then
              OldPosition = Position
            Else
              ' if the found position is smaller than the parameter MaxCharacters 
              ' then search the next space and check the position again          
              While (Position > 0 And Position <= MaxCharacters)
                OldPosition = Position
                Position = InStr(Position + 1, Help, " ")
              Wend
              If (OldPosition <= NumberOfSpaces + Len(NextPrefix)) Then
                OldPosition = Position
              End If
            End If

            '--------------------------------------------------------------------------
            ' all signs until the found position may be added to the character string 
            ' and all signs from the found position are stored for the further 
            ' workmanship
            '--------------------------------------------------------------------------
            ' cut all characters until OldPosition
            LeftCharacters = Left(Help, OldPosition)
            Output = Output & LeftCharacters & vbCrLf
            ' cut all characters from OldPosition
            Help = Space(NumberOfSpaces) & NextPrefix & Right(Help, Len(Help) - OldPosition)

            ' for the last line 
            If (Len(Help) <= MaxCharacters) Then
              Output = Output & Help
            End If 
 
          End If
        Loop Until (Len(Help) <= MaxCharacters)
      End If
    Else
      Output = Help
    End If
  End If

  FormatText = Output
  Exit Function

FormatTextError:
  FormatText = ""
End Function


'*****************************************************************************
'Description:
'        This function formates a string for the module description in 
'        generated module header.
'-----------------------------------------------------------------------------
'Parameters:
'        v                string (module description)
'-----------------------------------------------------------------------------
'Returns:
'        formatted string
'*****************************************************************************
Function FormatModuleDescription(v As String) As String
On Error Resume Next
  FormatModuleDescription = FormatText(0, MODULE_PREFIX_FIRST_LINE, MODULE_PREFIX_NEXT_LINE, v, MAX_CHARACTERS_FOR_SOURCE)
End Function


'*****************************************************************************
'Description:
'          This function formates a string for the disable tooltips.
'
'          Example 1:
'              .DisabledTooltipText = FormatDisabledToolTip("this pin is used as general IO")
'
'              |- this pin is used as general IO     
'
'          Example 2:
'              .DisabledTooltipText = TOOLTIP_DISABLED_IF
'              .DisabledTooltipText = .DisabledTooltipText & FormatDisabledToolTip("this pin is used as general IO")
'
'              |This control is disabled because: 
'              |- this pin is used as general IO     
'-----------------------------------------------------------------------------
'Parameters:
'        v                string 
'-----------------------------------------------------------------------------
'Returns:
'        formatted string
'*****************************************************************************
Public Function FormatDisabledToolTip(v As String) As String
On Error Resume Next
  FormatDisabledToolTip = vbCrLf & FormatText(0,TOOLTIP_PREFIX_FIRST_LINE, TOOLTIP_PREFIX_NEXT_LINE, v, MAX_CHARACTERS_FOR_TOOLTIPS) 
End Function


'*****************************************************************************
' @bfunc   Public | FormatNormalToolTip | String |
'
'-----------------------------------------------------------------------------
'          This function formates a string for the tooltips without prefix.
'
'          Example 1:
'              .DisabledTooltipText = FormatNormalToolTip(TOOLTIP_DISABLED_FUNCTION)
'
'              |This function or macro can not be selected because it does
'              |not suit the present configuration.     
'
'-----------------------------------------------------------------------------
' @rdesc   formatted string
'
'-----------------------------------------------------------------------------
' @bparm   | v | String | text 
'
'*****************************************************************************
Public Function FormatNormalToolTip(v As String) As String
On Error Resume Next
  FormatNormalToolTip = FormatText(0, "", "", v, MAX_CHARACTERS_FOR_TOOLTIPS) 
End Function


'*****************************************************************************
' @bfunc   Public | FormatMessageBoxText | String |
'
'-----------------------------------------------------------------------------
'          This function formates a string for the message box output text
'          without prefix.
'
'-----------------------------------------------------------------------------
' @rdesc   formatted string
'
'-----------------------------------------------------------------------------
' @bparm   | v | String | text 
'
'*****************************************************************************
Public Function FormatMessageBoxText(v As String) As String
On Error Resume Next
  FormatMessageBoxText = FormatText(0, "", "", v, MAX_CHARACTERS_FOR_MSG_TEXT) 
End Function


'*****************************************************************************
' @bfunc   Public | GetDisabledFunctionTooltipEntry | String |
'
'-----------------------------------------------------------------------------
'          This function returns the first sentence for a disabled tooltip for 
'          a function or macro. 
'
'-----------------------------------------------------------------------------
' @rdesc   formatted string
'
'-----------------------------------------------------------------------------
' @bparm   | func | FunctionClass | reference to this object 
' @bparm   | sFunctionName | String | function or macro name as identifiere for the object 
'
'*****************************************************************************
Public Function GetDisabledFunctionTooltipEntry(func As FunctionClass, sFunctionName As String) As String
On Error Goto GetDisabledFunctionTooltipEntryError

  Select Case func.FunctionSort(sFunctionName)
      Case 0  ' macro
           GetDisabledFunctionTooltipEntry = TOOLTIP_DISABLED_MACRO
      Case 1  ' function
           GetDisabledFunctionTooltipEntry = TOOLTIP_DISABLED_FUNCTION
      Case 2  ' ISR
           GetDisabledFunctionTooltipEntry = ""
      Case 3  ' Trap
           GetDisabledFunctionTooltipEntry = TOOLTIP_DISABLED_TRAP
  End Select

  Exit Function

GetDisabledFunctionTooltipEntryError:
  GetDisabledFunctionTooltipEntry = ""
End Function


'*****************************************************************************
' @bfunc   Public | FormatFunctionToolTip | String |
'
'-----------------------------------------------------------------------------
'          This function formates a string for a function or macro 
'          description tooltips. 
'
'-----------------------------------------------------------------------------
' @rdesc   formatted string
'
'-----------------------------------------------------------------------------
' @bparm   | r | ProjectData | set of the registers
' @bparm   | func | FunctionClass | reference to this object 
' @bparm   | sFunctionName | String | function or macro name as identifiere for the object 
'
'*****************************************************************************
Public Function FormatFunctionToolTip(r As ProjectData, func As FunctionClass, sFunctionName As String) As String
On Error Goto FormatFunctionToolTipError

    Const MAX_CHARACTERS_FOR_FUNC_TOOLTIPS = 80
    Const BLANKS_FOR_FUNC_TOOLTIPS = 15

    Dim l As Long
    Dim s As String
    Dim sParameterName As String
    Dim sParameterList As String
    Dim sParameterDescription As String
    Dim lParameterCount As Long
    Dim sSign1 As String
    Dim sSign2 As String
    Dim sSign3 As String
    Dim sHelp As String
    Dim sLeftCharacters As String
    Dim lPosition As Long

    lParameterCount = func.ParameterCount(sFunctionName)
    If (lParameterCount = 0) Then
      Select Case func.FunctionSort(sFunctionName)
          Case 0
               sParameterList = ""
          Case 1
               sParameterList = "void"
          Case 2            ' ISR
               sParameterList = "void"
          Case 3            ' Trap
               sParameterList = "void"
      End Select
      sParameterDescription = Space(BLANKS_FOR_FUNC_TOOLTIPS) & "None"
    Else
      sParameterList = ""
      sParameterDescription = ""
      sSign1 = ", "
      sSign2 = vbCrLf
    	 For l = 1 To lParameterCount
        If (l = lParameterCount) Then
          sSign1 = ""
          sSign2 = ""
        End If
        sParameterName = func.ParameterName(sFunctionName, l)
        sSign3 = func.ParameterType(sParameterName)
        If (sSign3 = "") Then
          sParameterList = sParameterList & func.Parameter(sParameterName) & sSign1 
        Else
          sParameterList = sParameterList & sSign3 & " " & func.Parameter(sParameterName) & sSign1 
        End If 
'        sParameterList = sParameterList & func.ParameterType(sParameterName) & " " & func.Parameter(sParameterName) & sSign1 
        sParameterDescription = sParameterDescription & FormatText(BLANKS_FOR_FUNC_TOOLTIPS, "", "", func.Parameter(sParameterName) & ": " & vbCrLf, MAX_CHARACTERS_FOR_FUNC_TOOLTIPS) & FormatText(BLANKS_FOR_FUNC_TOOLTIPS + 5, "", "", func.ParameterDescription(sParameterName), MAX_CHARACTERS_FOR_FUNC_TOOLTIPS)  & sSign2
     	Next l
    End If

    Select Case func.FunctionSort(sFunctionName)
        Case 0
             s = "Macro:" & vbCrLf
        Case 1
             s = "Function:" & vbCrLf
        Case 2            ' ISR
             s = "Function:" & vbCrLf
        Case 3            ' Trap
             s = "Function:" & vbCrLf
    End Select

    sHelp = func.FunctionType(sFunctionName) & " " & r.v(sFunctionName) & " (" & sParameterList & ") "
    s = s & FormatText(BLANKS_FOR_FUNC_TOOLTIPS, "", "", sHelp, MAX_CHARACTERS_FOR_FUNC_TOOLTIPS) & vbCrLf


    s = s &  "Description:" & vbCrLf
    sHelp = func.FunctionDescription(sFunctionName)
    lPosition = InStr(1, sHelp, vbCrLf)  ' search for the first vbCrLf
    If (lPosition = 0) Then
      s = s & FormatText(BLANKS_FOR_FUNC_TOOLTIPS, "", "", sHelp, MAX_CHARACTERS_FOR_FUNC_TOOLTIPS)  & vbCrLf
    Else
      While (lPosition > 0)
        '--------------------------------------------------------------------------
        ' all signs until the found position may be added to the character string 
        ' and all signs from the found position are stored for the further 
        ' workmanship
        '--------------------------------------------------------------------------
        ' get all characters until vbCrLf
        sLeftCharacters = Left(sHelp, lPosition - 1)
        s = s & FormatText(BLANKS_FOR_FUNC_TOOLTIPS, "", "", sLeftCharacters, MAX_CHARACTERS_FOR_FUNC_TOOLTIPS)  & vbCrLf
       ' get all characters from vbCrLf
        sHelp = Right(sHelp, Len(sHelp) - lPosition - Len(vbCrLf) + 1)
        lPosition = InStr(1, sHelp, vbCrLf)  ' search for the first vbCrLf
        If (lPosition = 0) Then
          s = s & FormatText(BLANKS_FOR_FUNC_TOOLTIPS, "", "", sHelp, MAX_CHARACTERS_FOR_FUNC_TOOLTIPS)  & vbCrLf
        End If
      Wend
    End If

    s = s &  "Returnvalue:" & vbCrLf
    s = s & FormatText(BLANKS_FOR_FUNC_TOOLTIPS, "", "", func.FunctionReturnvalue(sFunctionName), MAX_CHARACTERS_FOR_FUNC_TOOLTIPS)  & vbCrLf

    s = s &  "Parameters:" & vbCrLf
    s = s & sParameterDescription
    FormatFunctionToolTip = s
    Exit Function

FormatFunctionToolTipError:
    FormatFunctionToolTip = ""
End Function


'*****************************************************************************
' @bfunc   Public | FormatFunctionHeader | String |
'
'-----------------------------------------------------------------------------
'          This function formates a string for a function or macro 
'          header in the generated code. 
'
'-----------------------------------------------------------------------------
' @rdesc   formatted string
'
'-----------------------------------------------------------------------------
' @bparm   | r | ProjectData | set of the registers
' @bparm   | func | FunctionClass | reference to this object 
' @bparm   | sFunctionName | String | function or macro name as identifiere for the object 
'
'*****************************************************************************
Public Function FormatFunctionHeader(r As ProjectData, func As FunctionClass, sFunctionName As String) As String
On Error Goto FormatFunctionHeaderError
  Const MAX_CHARACTERS_FOR_TAG = 16
  Const TAG_PARAMETERS  = " @Parameters"
  Const TAG_FUNCTION    = " @Function"
  Const TAG_MACRO       = " @Macro"
  Const TAG_DESCRIPTION = " @Description"
  Const TAG_RETURNVALUE = " @Returnvalue"
  Const TAG_DATE        = " @Date"

  Dim l As Long
  Dim s As String
  Dim sParameterName As String
  Dim sParameterList As String
  Dim sParameterDescription As String
  Dim lParameterCount As Long
  Dim sSign1 As String
  Dim sSign2 As String
  Dim sSign3 As String
  Dim sHelp As String
  Dim sPrefixFirstLine As String
  Dim sPrefixNextLine As String
  Dim sLeftCharacters As String
  Dim lPosition As Long
  Dim sBorderInside As String
  Dim sBorderOutside As String

  sPrefixNextLine = COMMENT_FOR_SOURCE_ONLY & Space(16)
  
  ' create the border lines for the header
  sBorderInside = COMMENT_FOR_SOURCE_ONLY 
  sBorderOutside = COMMENT_FOR_SOURCE_ONLY
  For l = 1 To MAX_CHARACTERS_FOR_SOURCE - Len(COMMENT_FOR_SOURCE_ONLY)
    sBorderInside = sBorderInside & CHARACTER_INSIDE_FUNCTION_HEADER
    sBorderOutside = sBorderOutside & CHARACTER_OUTSIDE_FUNCTION_HEADER
  Next l

  lParameterCount = func.ParameterCount(sFunctionName)
  sPrefixFirstLine = COMMENT_FOR_SOURCE_ONLY & TAG_PARAMETERS & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_PARAMETERS)) 
  If (lParameterCount = 0) Then
    Select Case func.FunctionSort(sFunctionName)
        Case 0
             sParameterList = ""
        Case 1
             sParameterList = "void"
        Case 2            ' ISR
             sParameterList = "void"
        Case 3            ' Trap
             sParameterList = "void"
    End Select

    sParameterDescription = sPrefixFirstLine & "None"
  Else
    sParameterList = ""
    sParameterDescription = ""
    sSign1 = ", "
    sSign2 = vbCrLf
  	 For l = 1 To lParameterCount
      If (l = lParameterCount) Then
        sSign1 = ""
        sSign2 = ""
      End If
      sParameterName = func.ParameterName(sFunctionName, l)
      sSign3 = func.ParameterType(sParameterName)
      If (sSign3 = "") Then
        sParameterList = sParameterList & func.Parameter(sParameterName) & sSign1 
      Else
        sParameterList = sParameterList & sSign3 & " " & func.Parameter(sParameterName) & sSign1 
      End If 
      sParameterDescription = sParameterDescription & FormatText(0, sPrefixFirstLine, sPrefixNextLine, func.Parameter(sParameterName) & ": ", MAX_CHARACTERS_FOR_SOURCE) & vbCrLf & FormatText(0, sPrefixNextLine, sPrefixNextLine, func.ParameterDescription(sParameterName), MAX_CHARACTERS_FOR_SOURCE)  & sSign2
   	Next l
  End If

  s = sBorderOutside & vbCrLf

  Select Case func.FunctionSort(sFunctionName)
      Case 0
           sPrefixFirstLine = COMMENT_FOR_SOURCE_ONLY & TAG_MACRO & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_MACRO)) 
      Case 1
           sPrefixFirstLine = COMMENT_FOR_SOURCE_ONLY & TAG_FUNCTION & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_FUNCTION)) 
      Case 2            ' ISR
           sPrefixFirstLine = COMMENT_FOR_SOURCE_ONLY & TAG_FUNCTION & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_FUNCTION)) 
      Case 3            ' Trap
           sPrefixFirstLine = COMMENT_FOR_SOURCE_ONLY & TAG_FUNCTION & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_FUNCTION)) 
  End Select

  sHelp = func.FunctionType(sFunctionName)
  If (sHelp = "") Then
    sHelp = r.v(sFunctionName) & "(" & sParameterList & ") "
  Else
    sHelp = sHelp & " " & r.v(sFunctionName) & "(" & sParameterList & ") "
  End If
  s = s & FormatText(0, sPrefixFirstLine, sPrefixNextLine, sHelp, MAX_CHARACTERS_FOR_SOURCE) & vbCrLf
  s = s & COMMENT_FOR_SOURCE_ONLY & vbCrLf
  s = s & sBorderInside & vbCrLf

  sPrefixFirstLine = COMMENT_FOR_SOURCE_ONLY & TAG_DESCRIPTION & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_DESCRIPTION)) 
  sHelp = func.FunctionDescription(sFunctionName)
  lPosition = InStr(1, sHelp, vbCrLf)  ' search for the first vbCrLf
  If (lPosition = 0) Then
    s = s & FormatText(0, sPrefixFirstLine, sPrefixNextLine, sHelp, MAX_CHARACTERS_FOR_SOURCE)  & vbCrLf
  Else
    While (lPosition > 0)
      '--------------------------------------------------------------------------
      ' all signs until the found position may be added to the character string 
      ' and all signs from the found position are stored for the further 
      ' workmanship
      '--------------------------------------------------------------------------
      ' get all characters until vbCrLf
      sLeftCharacters = Left(sHelp, lPosition - 1)
      s = s & FormatText(0, sPrefixFirstLine, sPrefixNextLine, sLeftCharacters, MAX_CHARACTERS_FOR_SOURCE)  & vbCrLf
      sPrefixFirstLine = sPrefixNextLine
     ' get all characters from vbCrLf
      sHelp = Right(sHelp, Len(sHelp) - lPosition - Len(vbCrLf) + 1)
      lPosition = InStr(1, sHelp, vbCrLf)  ' search for the first vbCrLf
      If (lPosition = 0) Then
        s = s & FormatText(0, sPrefixFirstLine, sPrefixNextLine, sHelp, MAX_CHARACTERS_FOR_SOURCE)  & vbCrLf
      End If
    Wend
  End If

  s = s & COMMENT_FOR_SOURCE_ONLY & vbCrLf
  s = s & sBorderInside & vbCrLf

  sPrefixFirstLine = COMMENT_FOR_SOURCE_ONLY & TAG_RETURNVALUE & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_RETURNVALUE)) 
  s = s & FormatText(0, sPrefixFirstLine, sPrefixNextLine, func.FunctionReturnvalue(sFunctionName), MAX_CHARACTERS_FOR_SOURCE)  & vbCrLf
  s = s & COMMENT_FOR_SOURCE_ONLY & vbCrLf
  s = s & sBorderInside & vbCrLf

  sPrefixFirstLine = COMMENT_FOR_SOURCE_ONLY & TAG_PARAMETERS & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_PARAMETERS)) 
  s = s & sParameterDescription & vbCrLf
  s = s & COMMENT_FOR_SOURCE_ONLY & vbCrLf

  s = s & sBorderInside & vbCrLf
  s = s & COMMENT_FOR_SOURCE_ONLY & TAG_DATE & Space(MAX_CHARACTERS_FOR_TAG - Len(TAG_DATE)) & Format(Now, "Short Date") & vbCrLf
  s = s & COMMENT_FOR_SOURCE_ONLY & vbCrLf
  s = s & sBorderOutside & vbCrLf
  FormatFunctionHeader = s
  Exit Function

FormatFunctionHeaderError:
  FormatFunctionHeader = ""
End Function


'*****************************************************************************
' @bfunc   Public | FormatFunctionDeclaration | String |
'
'-----------------------------------------------------------------------------
'          This function formates a string for a function or macro 
'          declaration in the generated code. 
'
'-----------------------------------------------------------------------------
' @rdesc   formatted string
'
'-----------------------------------------------------------------------------
' @bparm   | r | ProjectData | set of the registers
' @bparm   | func | FunctionClass | reference to this object 
' @bparm   | sFunctionName | String | function or macro name as identifiere for the object 
'
'*****************************************************************************
Public Function FormatFunctionDeclaration(r As ProjectData, func As FunctionClass, sFunctionName As String) As String
On Error Goto FormatFunctionDeclarationError

  Dim l As Long
  Dim sParameterName As String
  Dim sParameterList As String
  Dim lParameterCount As Long
  Dim sSign1 As String
  Dim sSign3 As String
  Dim sHelp As String

  lParameterCount = func.ParameterCount(sFunctionName)
  If (lParameterCount = 0) Then
    Select Case func.FunctionSort(sFunctionName)
        Case 0
             sParameterList = ""
        Case 1
             sParameterList = "void"
        Case 2            ' ISR
             sParameterList = "void"
        Case 3            ' Trap
             sParameterList = "void"
    End Select
  Else
    sParameterList = ""
    sSign1 = ", "
  	 For l = 1 To lParameterCount
      If (l = lParameterCount) Then
        sSign1 = ""
      End If
      sParameterName = func.ParameterName(sFunctionName, l)
      sSign3 = func.ParameterType(sParameterName)
      If (sSign3 = "") Then
        sParameterList = sParameterList & func.Parameter(sParameterName) & sSign1 
      Else
        sParameterList = sParameterList & sSign3 & " " & func.Parameter(sParameterName) & sSign1 
      End If 
   	Next l
  End If

  sHelp = func.FunctionType(sFunctionName)
  If (sHelp = "") Then
    sHelp = r.v(sFunctionName) & "(" & sParameterList & ")"
  Else
    sHelp = sHelp & " " & r.v(sFunctionName) & "(" & sParameterList & ")"
  End If

  ' a function / macro declaration should be in one line or ... a special sign must be insert
'  FormatFunctionDeclaration = FormatText(0, "", "", sHelp, MAX_CHARACTERS_FOR_SOURCE)
  FormatFunctionDeclaration = sHelp
  Exit Function

FormatFunctionDeclarationError:
  FormatFunctionDeclaration = ""
End Function


'*****************************************************************************
' @bfunc   Public | FormatParameterToolTip | String |
'
'-----------------------------------------------------------------------------
'          This function formates a string for a parameter
'          description tooltips. 
'
'-----------------------------------------------------------------------------
' @rdesc   formatted string
'
'-----------------------------------------------------------------------------
' @bparm   | r | ProjectData | set of the registers
' @bparm   | para | ParameterClass | reference to this object 
' @bparm   | sParameterName | String | parameter name as identifiere for the object 
'
'*****************************************************************************
Public Function FormatParameterToolTip(r As ProjectData, para As ParameterClass, sParameterName As String) As String
On Error Goto FormatParameterToolTipError

    Const MAX_CHARACTERS_FOR_PARA_TOOLTIPS = 80
    Const BLANKS_FOR_PARA_TOOLTIPS = 15

    Dim l As Long
    Dim s As String
    Dim sHelp As String
    Dim sLeftCharacters As String
    Dim lPosition As Long

    s = "Parameter:" & vbCrLf
    sHelp = r.v(sParameterName)
    s = s & FormatText(BLANKS_FOR_PARA_TOOLTIPS, "", "", sHelp, MAX_CHARACTERS_FOR_PARA_TOOLTIPS) & vbCrLf

    s = s &  "Description:" & vbCrLf
    sHelp = para.ParameterDescription(sParameterName)

    lPosition = InStr(1, sHelp, vbCrLf)  ' search for the first vbCrLf
    If (lPosition = 0) Then
      s = s & FormatText(BLANKS_FOR_PARA_TOOLTIPS, "", "", sHelp, MAX_CHARACTERS_FOR_PARA_TOOLTIPS)
    Else
      While (lPosition > 0)
        '--------------------------------------------------------------------------
        ' all signs until the found position may be added to the character string 
        ' and all signs from the found position are stored for the further 
        ' workmanship
        '--------------------------------------------------------------------------
        ' get all characters until vbCrLf
        sLeftCharacters = Left(sHelp, lPosition - 1)
        s = s & FormatText(BLANKS_FOR_PARA_TOOLTIPS, "", "", sLeftCharacters, MAX_CHARACTERS_FOR_PARA_TOOLTIPS)  & vbCrLf
       ' get all characters from vbCrLf
        sHelp = Right(sHelp, Len(sHelp) - lPosition - Len(vbCrLf) + 1)
        lPosition = InStr(1, sHelp, vbCrLf)  ' search for the first vbCrLf
        If (lPosition = 0) Then
          s = s & FormatText(BLANKS_FOR_PARA_TOOLTIPS, "", "", sHelp, MAX_CHARACTERS_FOR_PARA_TOOLTIPS)
        End If
      Wend
    End If

    FormatParameterToolTip = s
    Exit Function

FormatParameterToolTipError:
    FormatParameterToolTip = ""
End Function


'*****************************************************************************
'Description:
'        This function formates a declaration of a parameter (#define statement)
'        Example:
'        Call FormatParameterStatement(r, para, "MODx_PARA_xxx", "value")
'
'        |// parameter description for parameter 'MODx_PARA_xxx'
'        |#define <name of parameter 'MODx_PARA_xxx'> value 
'        |
'
'-----------------------------------------------------------------------------
' @rdesc   formatted string
'
'-----------------------------------------------------------------------------
' @bparm   | r | ProjectData | set of the registers
' @bparm   | para | ParameterClass | reference to this object 
' @bparm   | sParameterName | String | parameter name as identifiere for the object 
' @bparm   | sStatement | String | value of the parameter 
'
'*****************************************************************************
Public Function FormatParameterStatement(r As ProjectData, para As ParameterClass, sParameterName As String, sStatement As String) As String  
  On Error Goto FormatParameterStatementError 
  Dim s As String

  s = FormatComments(0, 0, "", "", para.ParameterDescription(sParameterName))
  s = s & vbCrLf & "#define " & r.v(sParameterName) & " " & sStatement & vbCrlf
  FormatParameterStatement = s
  Exit Function

FormatParameterStatementError:
  FormatParameterStatement = ""
  Exit Function
End Function

'*****************************************************************************
'Description:
'        This function formates a string for a comment line.
'        Example:
'        Call FormatComments(2, 1, "- ", "  ", "text in the first line text in all following line")
'
'        |  ///  - text in the first line
'        |  ///    text in all following 
'        |  ///    lines
'
'-----------------------------------------------------------------------------
'Parameters:         
'        iSpaces               specifies the number of leading spaces
'        iStyle                specifies the comment sign 
'                              0 => comment only in source
'                              1 => comment in source and dokumentation
'                              2 => comment in source and warning in docu
'        sPrefixFirstLine      string after the comment sign for the first line
'        sPrefixNextLine       string after the comment sign for all following lines
'        sComment              string with the text to be formatted
'-----------------------------------------------------------------------------
'Returns:
'*****************************************************************************
Public Function FormatComments(iSpaces As Integer, iStyle As Integer, sPrefixFirstLine As String, sPrefixNextLine As String, sComment As String) As String
On Error Goto FormatCommentsError

  Dim sFirstPrefix As String
  Dim sNextPrefix As String

  Select Case iStyle
      Case  1     ' comment which was show in the documentation file too
          sFirstPrefix = COMMENT_FOR_SOURCE_AND_DOCU & Space(2) & sPrefixFirstLine
          sNextPrefix =  COMMENT_FOR_SOURCE_AND_DOCU & Space(2) & sPrefixNextLine
      Case  2     ' comment which was show in the documentation file (as warning) too
          sFirstPrefix = COMMENT_FOR_WARNINGS & Space(1) & sPrefixFirstLine
          sNextPrefix =  COMMENT_FOR_WARNINGS & Space(1) & sPrefixNextLine
      Case Else   ' comments only in the generated source code
          sFirstPrefix = COMMENT_FOR_SOURCE_ONLY & Space(3) & sPrefixFirstLine
          sNextPrefix =  COMMENT_FOR_SOURCE_ONLY & Space(3) & sPrefixNextLine
  End Select

  FormatComments = FormatText(iSpaces, sFirstPrefix, sNextPrefix, sComment, MAX_CHARACTERS_FOR_SOURCE)
  Exit Function

FormatCommentsError:
  FormatComments = ""
End Function


'*****************************************************************************
'Description:
'        This function formates a string for a comment line in the generated
'        initialization function. 
'
'        Example:
'        FormatCommentsForInit(1, "text in the first line text in all following line")
'
'        |  ///  - text in the first line
'        |  ///    text in all following 
'        |  ///    lines
'
'-----------------------------------------------------------------------------
'Parameters:         
'        iStyle                specifies the prefix 
'                              0 => comment only in source
'                              1 => comment in source and dokumentation
'                              2 => comment in source and warning in doku
'        sComment              string with the text to be formatted
'-----------------------------------------------------------------------------
'Returns:
'*****************************************************************************
Public Function FormatCommentsForInit(iStyle As Integer, sComment As String) As String
On Error Goto FormatCommentsForInitError

  FormatCommentsForInit = FormatComments(2, iStyle, "- ", "  ", sComment)
  Exit Function

FormatCommentsForInitError:
  FormatCommentsForInit = ""
End Function


'*****************************************************************************
'Description:
'        This function formates a string for a comment line in the generated
'        initialization function. 
'
'        Example:
'        FormatCommentsForSource(6, 0, "text in the first line")
'
'        |      //   text in the first line
'
'-----------------------------------------------------------------------------
'Parameters:         
'        iSpaces               specifies the number of leading spaces
'        iStyle                specifies the prefix 
'                              0 => comment only in source
'                              1 => comment in source and dokumentation
'                              2 => comment in source and warning in doku
'        sComment              string with the text to be formatted
'-----------------------------------------------------------------------------
'Returns:
'*****************************************************************************
Public Function FormatCommentsForSource(iSpaces As Integer, iStyle As Integer, sComment As String) As String
On Error Goto FormatCommentsForSourceError

  FormatCommentsForSource = FormatComments(iSpaces, iStyle, "", "", sComment)
  Exit Function

FormatCommentsForSourceError:
  FormatCommentsForSource = ""
End Function


'*****************************************************************************
'Description:
'        This function formates a string for a code assignment statement 
'        in the generated initialization function. 
'
'        Example:
'        Call FormatCodeStatemente(2, "SSCO_CLC", "=", FormatTextOutput(v, "H4"), "load clock control register)
'        Call FormatCodeStatemente(2, "SSCO_CON", "|=", "~" & FormatTextOutput(v, "H4"), "load control register)
'
'        |  SSC0_CLC    =  0x0100         // load clock control register
'        |  SSC0_CON   |= ~0x0008         // load control register
'
'-----------------------------------------------------------------------------
'Parameters:         
'        iSpaces               number of leading spaces
'        sRegName              regsiter name
'        sOperator             operator
'        vValue                register value
'        sComment              string with comment for this code line
'-----------------------------------------------------------------------------
'Returns:
'*****************************************************************************
Public Function FormatCodeStatemente(iSpaces As Integer, sRegName As String, sOperator As String, _
                                     vValue As Variant, Optional sComment As String = "") As String
On Error Goto FormatCodeStatementeError
  ' constant for the minimum number of characters for the sSign and the comments
  Const MIN_CHARACTERS_COMMENTS = 10 
  Const TAB_ONE = 15
  Const TAB_TWO = 18
  Const TAB_THREE = 32

  Dim sHelp As String
  Dim iHelp As Integer
  Dim sSign As String

  sSign = " " & COMMENT_FOR_SOURCE_ONLY & " "

  FormatCodeStatemente = ""
  ' only if the requested line is not to long
  If (iSpaces + Len(sRegName) + Len(sOperator) + 2 + Len(vValue) + Len(sSign) + MIN_CHARACTERS_COMMENTS <= MAX_CHARACTERS_FOR_SOURCE) Then
    sHelp = Space(iSpaces) & sRegName

    ' if the length of sHelp greater than it shoud be
    If (Len(sHelp) > TAB_ONE) Then
      iHelp = 0
    Else
      iHelp = TAB_ONE - Len(sHelp)
    End If
    sHelp = sHelp & Space(iHelp)

    If (sOperator <> "") Then
      If (Instr(sOperator, "=") > 1) Then
        sHelp = sHelp & " " & sOperator & " "
      Else
        sHelp = sHelp & "  " & sOperator & " "
      End If

      ' if the length of sHelp greater than it shoud be
      If (Len(sHelp) > TAB_TWO) Then
        iHelp = 0
      Else
        iHelp = TAB_TWO - Len(sHelp)
      End If
      sHelp = sHelp & Space(iHelp)
    End If


    If (vValue <> "") Then
      If (Instr(vValue, "~") > 0) Then
        sHelp = sHelp & "" & vValue & ";"
      Else
        sHelp = sHelp & " " & vValue & ";"
      End If
    End If

    ' if the length of sHelp greater than it shoud be
    If (Len(sHelp) > TAB_THREE) Then
      iHelp = 0
    Else
      iHelp = TAB_THREE - Len(sHelp)
    End If
    sHelp = sHelp & Space(iHelp)

    iHelp = Len(sHelp)
    If (sComment <> "") Then
      sHelp = sHelp & sSign & sComment
    End If

    FormatCodeStatemente = FormatText(0, "", Space(iHelp) & sSign, sHelp, MAX_CHARACTERS_FOR_SOURCE)
  End If
  Exit Function

FormatCodeStatementeError:
  FormatCodeStatemente = ""
End Function


'*****************************************************************************
'Description:
'        This function formates a section header in the generated code.
'
'        Example:
'        Call FormatSectionHeader(2, 1, "text")
'
'        |  ///  -------------------------------------------------------
'        |  ///  text
'        |  ///  -------------------------------------------------------
'
'-----------------------------------------------------------------------------
'Parameters:         
'        iSpaces               number of leading spaces
'        iStyle                specifies the prefix 
'                              0 => comment only in source
'                              1 => comment in source and dokumentation
'                              2 => comment in source and warning in doku
'        sComment              string with text
'-----------------------------------------------------------------------------
'Returns:
'*****************************************************************************
Public Function FormatSectionHeader(iSpaces As Integer, iStyle As Integer, sComment As String) As String
On Error Goto FormatSectionHeaderError

  Dim sHelp As String
  Dim sBorder As String
  Dim iHelp As Integer
  Dim i As Integer
  
  FormatSectionHeader = ""

  sHelp = Space(iSpaces)
  Select Case iStyle
      Case  1     ' comment which was show in the documentation file too
          sHelp =  sHelp & COMMENT_FOR_SOURCE_AND_DOCU & Space(2)
      Case  2     ' comment which was show in the documentation file (as warning) too
          sHelp =  sHelp & COMMENT_FOR_WARNINGS & Space(1)
      Case Else   ' comments only in the generated source code
          sHelp =  sHelp & COMMENT_FOR_SOURCE_ONLY & Space(3)
  End Select

  iHelp = MAX_CHARACTERS_FOR_SOURCE - Len(sHelp)
  sBorder = sHelp
  For i = 1 To iHelp
    sBorder = sBorder & CHARACTER_BORDER_SECTIONS
  Next i

  sHelp = FormatText(0, "", sHelp, sHelp & sComment, MAX_CHARACTERS_FOR_SOURCE)

  FormatSectionHeader = sBorder & vbCrLf & sHelp & vbCrLf & sBorder
  Exit Function

FormatSectionHeaderError:
  FormatSectionHeader = ""
End Function


'*****************************************************************************
'Description:
'        This function appends spaces after a string up to the requested 
'        total length. If the length of the passed string is equal or greater
'        than the requested total length, no spaces will be appended.
'
'        Examples:
'        FillRight(6, "Peter")    returns "Peter "
'        FillRight(6, "William")  returns "William"
'
'-----------------------------------------------------------------------------
'Parameters:
'        lLen   total length with spaces
'        sStr   input string
'-----------------------------------------------------------------------------
'Returns:
'        formatted string
'*****************************************************************************
Public Function FillRight(lLen As Long, sStr As String) As String
    On Error Resume Next
    Dim lStrLen As Long

    lStrLen = Len(sStr)
    If (lStrLen >= lLen) Then
        FillRight = sStr
    Else
        FillRight = sStr & Space(lLen - lStrLen)
    End If
End Function
