Commit 1f739469 authored by Benoît Minisini's avatar Benoît Minisini

Put 'gbh3' back into the git repository.

[CONFIGURATION]
* BUG: Don't put main/tools in .gitignore.

[HELPER]
* BUG: Put 'gbh3' back into the git repository.
parent aa66e9bc
......@@ -35,7 +35,7 @@ missing
*.mo
*.gambas
main/trunk_version.h
main/*/gb*3
main/gb*/gb*3
DISABLED*
.startup
.settings
......
[Desktop Entry]
Icon=./.icon.png
# Gambas Project File 3.0
# Compiled with Gambas 3.6.90
Title=gbh3
Startup=MMain
Icon=icon.png
Version=3.6.90
VersionFile=1
Description="Extract help comments from C/C++ source files and format them into a .help file."
Authors="(C) 2014 Tobias Boege <tobias@gambas-buch.de>, GPLv2+"
TabSize=2
Language=en_GB
Packager=1
This diff is collapsed.
' Gambas module file
' ' Gambas module file
'
' Private $sRoot As String
' Private $sComponent As String
' Private $bVerbose As Boolean
'
' Private Sub PrintError(sErr As String)
'
' Error File.Name(Args[0]); ": error: "; sErr
' Quit 1
'
' End
'
' Private Sub PrintMessage(sMsg As String)
'
' If Not $bVerbose Then Return
' Error sMsg
'
' End
'
' Public Sub Main()
'
' Dim iInd As Integer, aSources As New String[]
' Dim sArg, sRec As String, aRec As String[]
' Dim sPath As String
' Dim hOut As File
' Dim bOnlySources As Boolean
' Dim sMsg As String
'
' $sRoot = System.Path
'
' For iInd = 1 To Args.Max
' Select Case Args[iInd]
' Case "-h", "--help"
' Print File.Load("usage")
' Quit
' Case "-V", "--version"
' Print Application.Version
' Quit
' Case "-L", "--license"
' Print File.Load("license")
' Quit
' Case "-v", "--verbose"
' $bVerbose = True
' Case "-r", "--root"
' $sRoot = Args[iInd + 1]
' If Not $sRoot Then PrintError(Args[iInd] & " requires an argument")
' Inc iInd
' Case "-c", "--component"
' $sComponent = Args[iInd + 1]
' If Not $sComponent Then PrintError(Args[iInd] & " requires an argument")
' Inc iInd
' Case "--"
' bOnlySources = True
' Default
' If Not bOnlySources Then
' If Args[iInd] Begins "-" Then
' PrintError("unknown option: " & Args[iInd])
' Endif
' Endif
' aSources.Add(Args[iInd])
' End Select
' Next
'
' If aSources.Count = 0 Then aSources.Add(".")
'
' If $sComponent Then
' sPath = $sRoot &/ "share/gambas" & System.Version &/ "info" &/ $sComponent & ".help"
' PrintMessage("Output to " & sPath)
' hOut = Open sPath For Create
' Else
' hOut = File.Out
' Endif
'
' For Each sArg In aSources
' If Left(sArg) <> "/" Then
' If sArg = "." Then
' sArg = Application.Dir
' Else
' sArg = Application.Dir &/ sArg
' Endif
' Endif
' If IsDir(sArg) Then
' aRec = RDir(sArg, "*.{c,cc,cpp}")
' For Each sRec In aRec
' OneFile(sArg &/ sRec, hOut)
' Next
' Else
' OneFile(sArg, hOut)
' Endif
' Next
'
' If $sComponent Then
' Close #hOut
' If Stat(sPath).Size = 0 Then
' PrintMessage("Removing void data file")
' Try Kill sPath
' Endif
' Endif
'
' Catch
'
' sMsg = Error.Text & ": " & Error.Backtrace.Join(" ")
' Output To Default
' PrintError(sMsg)
'
' End
'
' Private Sub OneFile(sPath As String, hOut As File)
'
' Dim hFile As File
'
' PrintMessage("Processing " & sPath & "...")
' hFile = Open sPath For Input
'
' MakeHelp(Translate(Extract(hFile), sPath), hOut)
'
' Close #hFile
'
' End
'
' Private Function Extract(hFile As File) As String[]
'
' Dim hNameFn As New RegExp, hNameInline As New RegExp
' Dim sLine As String, sInline As String
' Dim aRes As New String[]
' Dim bRecord As Boolean
'
' hNameFn.Compile("^BEGIN_.*\\(([^,)]+).*")
' hNameInline.Compile("/\\*\\*G (.+)$")
'
' For Each sLine In hFile.Lines
' If sLine Match "^[\\t ]*\\*?\\*/$" Then
' If sInline Then
' aRes.Add("G " & sInline)
' sInline = ""
' bRecord = False
' Endif
' Continue
' Endif
' hNameFn.Exec(sLine)
' If hNameFn.Offset <> -1 And If bRecord And If Not sInline Then
' aRes.Add(hNameFn[1].Text)
' bRecord = False
' Endif
'
' If bRecord Then aRes.Add(RegExp.Replace(sLine, "^[\\t ]*\\*", "'"))
'
' If sLine Match "^/\\*\\*G$" Then
' If bRecord Then aRes.Add("ERROR")
' sInline = ""
' bRecord = True
' Endif
' hNameInline.Exec(sLine)
' If hNameInline.Offset <> -1 Then
' If bRecord Then aRes.Add("ERROR")
' sInline = LTrim$(hNameInline[1].Text)
' bRecord = True
' Endif
' Next
' If bRecord Then aRes.Add("ERROR")
' Return aRes
' End
'
' Private Function Translate(aSource As String[], sPath As String) As String[]
'
' Dim sLine As String, aRes As New String[]
'
' For Each sLine In aSource
' If Not sLine Then Continue
' If sLine = "ERROR" Or If sLine Begins "'" Then
' aRes.Add(sLine)
' Continue
' Endif
' If sLine Begins "G " Then ' Syntax-2?
' aRes.Add(Right$(sLine, -2))
' Continue
' Endif
' ' Syntax-1
' aRes.Add(GetSyntax1(sLine, sPath))
' Next
' Return aRes
' End
'
' Private Function GetSyntax1(sFunc As String, sPath As String) As String
'
' Dim hClassName As New RegExp, hFunction As New RegExp
' Dim hFile As File, sLine, sClass As String
' Dim aRes As New String[]
'
' hClassName.Compile("GB_DECLARE\\(\\\"([^\\\"]+).*")
' hFunction.Compile("GB_[^(]+\\(\\\"([^\"]+)\\\".*" & sFunc & "\\W")
'
' hFile = Open sPath For Input
' sClass = "ERROR"
' For Each sLine In hFile.Lines
' If Not sLine Then Continue
' hClassName.Exec(sLine)
' If hClassName.Offset <> -1 Then sClass = hClassName[1].Text
' hFunction.Exec(sLine)
' If hFunction.Offset <> -1 Then
' If Not aRes.Count Then aRes.Add(sClass)
' aRes.Add(hFunction[1].Text)
' Endif
' Next
' Close #hFile
' Return aRes.Join(" ")
' End
'
' Public Sub MakeHelp(aSource As String[], hOut As File)
'
' Dim sLine, sCls, sSym As String
' Dim cHelp As New Collection, aCurrent As New String[]
' Dim cClass As Collection, aHelp, aSyn As String[]
' Dim iInd As Integer
'
' Output To hOut
' For Each sLine In aSource
' If Not sLine Then Continue
' If sLine Begins "'" Then
' aCurrent.Add(sLine)
' Else
' With Scan(sLine, "* *")
' If .Count = 0 Then ' <Class>
' sCls = sLine
' sSym = "#"
' Else If .Count = 2 Then ' <Class> <Symbol-and-Synonym-List>
' sCls = Trim$(.[0])
' sSym = Trim$(.[1])
' Endif
' If Not cHelp[sCls] Then cHelp[sCls] = New Collection
' cHelp[sCls][sSym] = aCurrent
' aCurrent = New String[]
' End With
' Endif
' Next
'
' For Each cClass In cHelp
' Print "#"; cHelp.Key
' aHelp = cClass["#"]
' If aHelp Then Print aHelp.Join("\n")
' For Each aHelp In cClass
' If cClass.Key = "#" Then Continue
' aSyn = Split(cClass.Key, " ")
' Print aSyn[0]
' If aHelp.Count Then Print aHelp.Join("\n")
' For iInd = 1 To aSyn.Max
' Print aSyn[iInd]
' Print "' A synonym for";; aSyn[0]; "."
' Next
' Next
' Next
' Output To Default
' End
About gbh3
----------
gbh3 is used to extract Gambas documentation from C/C++ source files and
create .help files for a component from them. It is a single Gambas project
depending only on gb.pcre.
... and why?
------------
Components written in Gambas can already be documented in-code. This docu-
mentation is then stored inside their .info files. With a similar result
provided by gbh3 for C/C++ components, we can document all[*] Gambas in
its source files (at least my components will be) which makes it, IMHO,
easier to keep the documentation up-to-date. Also the help could be
displayed locally by the IDE or remotely once these .help files are imported
to the gambaswiki.org site.
Also, documentation can be bound to a specific source code version, so that
you get docs for the version of Gambas you are running, not only for the
development branch.
[*] I'm not sure about intrinsic functions, though. Should be feasible,
looking at gbx_class_info.c...
Great! How do I prepare my component?
-------------------------------------
The No. 0 rule is to BE CAREFUL! There are quite some rules to remember:
1. Documentation syntax.
You may write a Gambas documentation comment like
/**G
* Here goes the documentation.
**/
BEGIN_METHOD_VOID(ClassName_MethodName)
/* ... */
END_METHOD
or alternatively
/**G Class Symbol
* Documenting Class.Symbol
**/
Instead of the **/ at the end, you may also write */. Cool, huh?
The second syntax can also be used to document the class per se:
/**G Class
* Class documentation here
**/
The difference between both notations is that the first must immediately
precede a BEGIN_{PROPERTY,METHOD,METHOD_VOID) line that defines the symbol
to which the documentation refers. The second syntax documents the indicated
symbol -- no matter where the comment is.
This is intended to document GB_CONSTANTs or GB_PROPERTY_SELFs which don't
have a BEGIN_* line. It can neverthelss be used for any other symbol but
NEVER intermix both syntaxes on a single symbol.
The ClassName_MethodName part I call "(implementation) function name". The
particular function naming convention shown is not mandatory. The scripts
take the function name and look up the corresponding symbol in your
GB_DESC[].
2. Regular expressions.
The regular expressions used to filter these comments are somewhat strict.
You have to pass the spaces exactly as indicated in the line where your
comment text starts, i.e. <space>*<space>text. Also note that Class and
Symbol in the second syntax are case sensitive!
OTOH, I can't guarantee that the expressions will not consume junk that you
left behind where I didn't expect junk to be.
3. Strict structure.
DON'T try to confuse the parsers by not giving information it needs where
it expects it.
4. Synonyms.
The first match for a function name lookup in a GB_DESC[] is taken as the
"primary" implementation of that symbol. That means the help comment will
be attched to that symbol. All other symbols which call the same function
are considered synonyms and are *automatically* documented with the default
sentence: "This is a synonym for <primary-symbol>". DO NOT document them
separately using a syntax-2 help block!
5. Don't reuse method and property implementations (except for synonyms).
As the implementation function name is searched in the GB_DESC[]s in your
source file, you may not put the same function into different classes -- or
the parser may get confused.
Also, keep the GB_DESC[] in the same source file as the help comment.
Umm... I need an example
------------------------
gb.openssl and gb.data are partially documented that way. Digest.Hash() and
Digest._call() in gb.openssl show how to deal with synonyms. There the entry
for Hash precedes the entry for _call, thus Hash is the primary symbol and
_call a synonym.
To see a sample .help file (on stdout), you can do at the source tree root:
$ gbx3 app/src/gbh3 -- gb.openssl
(c) Tobias Boege, Benoît Minisini
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or
(at your option) any later version.
Extract Gambas help comments from source files.
Usage: gbh3 [options] [<sources>]
Options:
-r --root <root> gives the Gambas installation directory
-c --component <component> generate help directly in a component '*.help' file
-V --version display version
-L --license display license
-h --help display this help
If <sources> contains directories, they are searched recursively for '*.c'
and '*.cpp' files. If <sources> is not specified, the current directory
is searched.
The extracted help is printed on the standard output, unless the '-c'
option is specified.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment