how to generate docs from *.bas *.bi files?

[D.J.Peters]

has anywhere modify doxygen docbook or any other tool that create html files from *.bi *.bas files with the standard tags "@usage @param ..." ?

Joshy

[KristopherWindsor]

You mean an FB program that could read source code and format it in HTML for syntax highlighting? I could make one. :-)

[stylin]

D.J.Peters, not that I know of.

Doxygen uses flex for its language parser, and all of the state info for the various languages is all mixed-in together. I've been wanting to add FB support, but I haven't had the time. There are a few VB filters for it floating around that could be modified for FB also.

Natural Docs seems like it would be much easier to add basic FB support to than Doxygen, modifying the existing Visual Basic language settings would not be too hard:
http://www.naturaldocs.org/customizinglanguages.html

[KristopherWindsor]

hello KristopherWindsor
if you have time to create an doc generator for FreeBASIC
i'm sure we will love your hard work :-)

you must parse one ".bas" input file and follow all it's included "*.bi" files.

docgen test.bas

if you find an document tag inside an block of comments
you must read and parse this tags for example:
@param @list @comment @see ...
(or any other tags defined by you)

you have not to create html for the whole code
only for the defined tags and the followed named thing

named things can be type/enum sub/function constructor/destuctor property ...

/'
@name testtype
@decription bla bla bla
@field name is bla bla bla
@field costs is bla bla bla
'/
type test
name as string * 64
costs as uinteger
end type

or

/'
@name min
@description bla bla bla bla bla
@paramin A is bla bla bla
@paramin B is bla bla bla
@return bla bla bla
'/
function min(A as integer,B as integer) as integer
...
...
end function

the html result can be:

Code: Select all

Function min(A As Integer,B As Integer) As Integer
bla bla bla bla bla
Input param A Is bla bla bla
Input param B Is bla bla bla
returns bla bla bla

let me know if you are the right man for this useful project.

Joshy

Why did you delete your post?

Anyway, I am trying to write one, but I need a function that will take a relative filename, such as "windows.bi," and find the absolute filename so I can open that .BI file. Can someone please write that function?

[maddogg6]

Anyway, I am trying to write one, but I need a function that will take a relative filename, such as "windows.bi," and find the absolute filename so I can open that .BI file. Can someone please write that function?

An easy work around would be to read a user editable .ini file - that contains path to \FB\Includes. This should be easy enough for any one who would use a doc maker to do - Id think.

[KristopherWindsor]

I don't think that will work. "windows.bi" may be in that folder, but I.E. "itech\setup.bi" may be relative to the Inc folder, or the exepath, or some other path. I think there is a list of paths where FBC looks for files to include, but I'm not sure where that list of paths is. :-)

[cha0s]

KW: check the compiler source.

[KristopherWindsor]

I tried, but I cannot understand it. :-|

Code: Select all

'':::::
private function hFindIncFile _
	( _
		byval incfilehash as THASH ptr, _
		byval filename as zstring ptr _
	) as zstring ptr static

	dim as string fname

	fname = ucase( *filename )

	function = hashLookup( incfilehash, fname )

end function

'':::::
private function hAddIncFile _
	( _
		byval incfilehash as THASH ptr, _
		byval filename as zstring ptr _
	) as zstring ptr static

    dim as zstring ptr fname, res
    dim as uinteger index

	fname = allocate( len( *filename ) + 1 )
	hUcase( filename, fname )

	index = hashHash( fname )

	res = hashLookupEx( incfilehash, fname, index )
	if( res = NULL ) then
		hashAdd( incfilehash, fname, fname, index )
	else
		deallocate( fname )
		fname = res
	end if

	function = fname

end function

There is a lot of code in hash.bas; I don't think the compiler has one simple function.

[D.J.Peters]

Why did you delete your post?

i don't renember me but nice if you will do a doc generator for us all.

Joshy
(by the way it isn't it a simple task but i'm sure you will get it work)

[KristopherWindsor]

Code: Select all

' <? FreeBASIC ?>
' FBDocumentGenerator v0.1
' (C) 2007 i-TECH and Kristopher Windsor

'Finds Subs, Functions, and Types through comments in the source code, and lists them in an HTML file (the output)
'Also finds the file name and description following "@program Program Name"
'Each object has the following properties, that can be defined in the comments:
'type and name                           (@sub makeimage)
'description                             (@description is a sub and then sub)
'follows                                 (@follows the screen_create sub)
'param         (subs and functions only) (@param iheight [integer] the height of the image)
'field         (types only)              (@field [integer] thingcounter)
'returns       (functions only)          (@returns rnd [double] a random number)
'note                                    (@note creates images for shared pointers)

'"follows" defines the objects that must be called, declared, or defined before a certain object can be called or defined
'If two definitions for "description", "follows", "param", "field", or "note" are given, the definitions will be combines.
'If any other object property is defined twice, the second definition is used.

'Does not curently check for .BI duplicates that could cause an endless documenting loop
'Does not process enums, constructors, or deconstructors
'Does not use indentation to make an outline of the files

Const t = Chr(9)
Const code_object_type_program = 1, code_object_type_type = 2, code_object_type_sub = 3, code_object_type_function = 4

'an array of these for subs, functions, types
'also one of these for each program
Type code_object
  As Integer Type
  As String Name
  As String description
  As Integer follow_total
  As String follows(1 To 32)
  As Integer param_total
  As String params(1 To 32)
  As Integer field_total
  As String fields(1 To 32)
  As String returns
  As Integer note_total
  As String notes(1 To 32)
End Type

Type code_include
  As String filename
  As Integer whichprogram 'points to code_program array
End Type

'lists the filename of included files to prevent duplicates, and points to the code_objects to specify the objects from the files
Type code_program
  As String filename_specified, filename_absolute
  As Integer code_include_total
  As code_include code_includes(1 To 32)
  As Integer code_object_total
  As code_object code_objects(0 To 256) 'code_object(0)
End Type

Dim Shared As Integer code_program_total = 0
Dim Shared As code_program code_programs(1 To 32) 'one for each file

Function code_program_file_name_absolute (relative As String) As String
  Return relative 'incomplete
End Function

Function code_object_type_to_string (whichtype As Integer) As String
  Select Case whichtype
  Case code_object_type_program
    Return "Program"
  Case code_object_type_type
    Return "Type"
  Case code_object_type_sub
    Return "Sub"
  Case code_object_type_function
    Return "Function"
  End Select
End Function

Sub code_parse (filename As String)
  Dim As Integer include_total, i
  Dim As String l, p

  Print "Processing " & filename & "..."

  code_program_total += 1

  With code_programs(code_program_total)
    .filename_specified = filename
    .filename_absolute = code_program_file_name_absolute(filename)

    Open filename For Input As #1
    If Err Then System
    While Not Eof(1)
      'l is one line
      Line Input #1, l
      l = Trim(l)
      'remove spacing and comment characters from l
      While Instr(Chr(9) + " '/", Left(l, 1)) > 0 And Len(l) > 1
        l = Right(l, Len(l) - 1)
      Wend
      'after comments are removed, the first character in l should be '@' or '#'
      Select Case Left(l, 1)
      Case "@"
        'add another object, or define the latest object
        i = Instr(l, " "): If i = 0 Then Error 66
        p = Trim(Right(l, Len(l) - i))
        Select Case Ucase(Left(l, i - 1))
        Case "@PROGRAM"
          .code_object_total = 0 'program cannot be defined after other things
          .code_objects(.code_object_total).type = code_object_type_program
          .code_objects(.code_object_total).name = p
        Case "@TYPE"
          .code_object_total += 1
          .code_objects(.code_object_total).type = code_object_type_type
          .code_objects(.code_object_total).name = p
        Case "@SUB"
          .code_object_total += 1
          .code_objects(.code_object_total).type = code_object_type_sub
          .code_objects(.code_object_total).name = p
        Case "@FUNCTION"
          .code_object_total += 1
          .code_objects(.code_object_total).type = code_object_type_function
          .code_objects(.code_object_total).name = p
        Case "@DESCRIPTION"
          .code_objects(.code_object_total).description += p + ". "
        Case "@FOLLOWS"
          .code_objects(.code_object_total).follow_total += 1
          .code_objects(.code_object_total).follows(.code_objects(.code_object_total).follow_total) = p
        Case "@PARAM"
          .code_objects(.code_object_total).param_total += 1
          .code_objects(.code_object_total).params(.code_objects(.code_object_total).param_total) = p
        Case "@FIELD"
          .code_objects(.code_object_total).field_total += 1
          .code_objects(.code_object_total).fields(.code_objects(.code_object_total).field_total) = p
        Case "@RETURNS"
          .code_objects(.code_object_total).returns = p
        Case "@NOTE"
          .code_objects(.code_object_total).note_total += 1
          .code_objects(.code_object_total).notes(.code_objects(.code_object_total).note_total) = p
        End Select
      Case "#"
        'add another object, or define the latest object
        i = Instr(l, " "): If i = 0 Then Error 66
        p = Trim(Right(l, Len(l) - i))
        'might include a file
        Select Case Ucase(Left(l, i - 1))
        Case "#INCLUDE"
          .code_include_total += 1
          .code_includes(.code_include_total).filename = Mid(p, 2, Len(p) - 2)
          Case Else :? Ucase(Left(l, i - 1))
        End Select
      End Select
    Wend
    Close #1

    'recursion to parse includes
    For a As Integer = 1 To .code_include_total
      .code_includes(a).whichprogram = code_program_total + 1 'create list of pointer to included files as they are parsed
      code_parse(.code_includes(a).filename)
    Next a
  End With
End Sub

Sub code_document_open
  Open Command + ".html" For Output As #2
  Print #2, "<html>"
  Print #2, t & "<head>"
  Print #2, t & t & "<title>" & code_programs(1).code_objects(0).name & "</title>"
  Print #2, t & t & "<style type=""text/css""><!-- div {padding-left: 30px; border: 3px solid;} --></style>"
  Print #2, t & "</head>"
  Print #2, t & "<body>"
  Print #2, t & t & "<h1 align=center>" & code_programs(1).code_objects(0).name & "</h1>"
End Sub

Sub code_document_close
  Print #2, t & "</body>"
  Print #2, "</html>"
  Close #2
End Sub

Sub code_document_toc_item (whichprogram As Integer, whichobject As Integer)
  With code_programs(whichprogram).code_objects(whichobject)
    Print #2, t & t & t & "<li>"
    Print #2, t & t & t & t & "<span title=""" & .description & """>"
    Print #2, t & t & t & t & t & "<a href=""#" & .name & """>"
    Print #2, t & t & t & t & t & .name & " (" & code_object_type_to_string(.type) & ")"
    Print #2, t & t & t & t & t & "</a>"
    Print #2, t & t & t & t & "</span>"
    Print #2, t & t & t & "</li>"
  End With
End Sub

Sub code_document_toc (whichprogram As Integer)
  If whichprogram = 1 Then
    Print #2, t & t & "<ul>"
  End If

  'add program to table of contents
  code_document_toc_item whichprogram, 0
  'add included files
  Print #2, t & t & "<ul>"
  For b As Integer = 1 To code_programs(whichprogram).code_include_total
    code_document_toc code_programs(whichprogram).code_includes(b).whichprogram
  Next b
  'add subs, functions, etc.
  For b As Integer = 1 To code_programs(whichprogram).code_object_total
    code_document_toc_item whichprogram, b
  Next b
  Print #2, t & t & "</ul>"

  If whichprogram = 1 Then
    Print #2, t & t & "</ul>"
  End If
End Sub

Sub code_document_main_item (whichprogram As Integer, whichobject As Integer, depth As Integer)
  With code_programs(whichprogram).code_objects(whichobject)
    Print #2, t & t & "<a name=""" & .name & """>&nbsp;</a>"
    Print #2, t & t & "<table width=100%>"
    Print #2, t & t & t & "<tr>"
    Print #2, t & t & t & t & t & "<td width=" & (depth * 5) & "%>&nbsp;</td>"
    Print #2, t & t & t & t & t & "<td width=" & (100 - depth * 5) & "%>"
    Print #2, t & t & t & t & t & t & "<div>"

    Print #2, t & t & t & t & t & t & "<h2>"
    Print #2, t & t & t & t & t & t & t & t & code_object_type_to_string(.type) & " " & .name
    Print #2, t & t & t & t & t & t & t & "</h2>"

    If whichobject = 0 Then
      Print #2, t & t & t & t & t & t & t & "<p>"
      Print #2, t & t & t & t & t & t & t & t & "Filename: <a href=""" & code_programs(whichprogram).filename_absolute & """>
      Print #2, t & t & t & t & t & t & t & t & code_programs(whichprogram).filename_absolute
      Print #2, t & t & t & t & t & t & t & t & "</a>"
      Print #2, t & t & t & t & t & t & t & "</p>"
    End If

    Print #2, t & t & t & t & t & t & t & "<p>"
    Print #2, t & t & t & t & t & t & t & t & .description
    Print #2, t & t & t & t & t & t & t & "</p>"

    If .follow_total Then
      Print #2, t & t & t & t & t & t & t & "<p>Follows the follwing objects:</p>"
      Print #2, t & t & t & t & t & t & t & "<ul>"
      For c As Integer = 1 To .follow_total
        Print #2, t & t & t & t & t & t & t & t & "<li>"
        Print #2, t & t & t & t & t & t & t & t & t & "<a href=""#" & .follows(c) & """>"
        Print #2, t & t & t & t & t & t & t & t & t & .follows(c)
        Print #2, t & t & t & t & t & t & t & t & t & "</a>"
        Print #2, t & t & t & t & t & t & t & t & "</li>"
      Next c
      Print #2, t & t & t & t & t & t & t & "</ul>"
    End If

    If .param_total Then
      Print #2, t & t & t & t & t & t & t & "<p>Accepts the following parameters:</p>"
      Print #2, t & t & t & t & t & t & t & "<ul>"
      For c As Integer = 1 To .param_total
        Print #2, t & t & t & t & t & t & t & t & "<li>"
        Print #2, t & t & t & t & t & t & t & t & t & .params(c)
        Print #2, t & t & t & t & t & t & t & t & "</li>"
      Next c
      Print #2, t & t & t & t & t & t & t & "</ul>"
    End If

    If .field_total Then
      Print #2, t & t & t & t & t & t & t & "<p>Defines the following fields:</p>"
      Print #2, t & t & t & t & t & t & t & "<ul>"
      For c As Integer = 1 To .field_total
        Print #2, t & t & t & t & t & t & t & t & "<li>"
        Print #2, t & t & t & t & t & t & t & t & t & .fields(c)
        Print #2, t & t & t & t & t & t & t & t & "</li>"
      Next c
      Print #2, t & t & t & t & t & t & t & "</ul>"
    End If

    If Len(.returns) Then
      Print #2, t & t & t & t & t & t & t & "<p>Returns:</p>"
      Print #2, t & t & t & t & t & t & t & "<ul>"
      Print #2, t & t & t & t & t & t & t & t & "<li>"
      Print #2, t & t & t & t & t & t & t & t & t & .returns
      Print #2, t & t & t & t & t & t & t & t & "</li>"
      Print #2, t & t & t & t & t & t & t & "</ul>"
    End If

    If .note_total Then
      Print #2, t & t & t & t & t & t & t & "<p>Notes:</p>"
      Print #2, t & t & t & t & t & t & t & "<ul>"
      For c As Integer = 1 To .note_total
        Print #2, t & t & t & t & t & t & t & t & "<li>"
        Print #2, t & t & t & t & t & t & t & t & t & .notes(c)
        Print #2, t & t & t & t & t & t & t & t & "</li>"
      Next c
      Print #2, t & t & t & t & t & t & t & "</ul>"
    End If

    Print #2, t & t & t & t & t & t & "</div></td></tr></table>"
  End With
End Sub

Sub code_document_main (whichprogram As Integer, depth As Integer = 0)
  'add program to table of contents
  code_document_main_item whichprogram, 0, depth
  'add included files
  For b As Integer = 1 To code_programs(whichprogram).code_include_total
    code_document_main code_programs(whichprogram).code_includes(b).whichprogram, depth + 1
  Next b
  'add subs, functions, etc.
  For b As Integer = 1 To code_programs(whichprogram).code_object_total
    code_document_main_item whichprogram, b, depth + 1
  Next b
  Print #2,
End Sub

Sub code_document
  code_document_open
  code_document_toc 1 'start recursiveness
  Print #2,
  code_document_main 1 'start recursiveness
  code_document_close
End Sub

code_parse Command
code_document

Print "Success!"
System

Okay, Joshy, I made the beta version! XD
It writes a table of contents at the top that links to each File / Sub / Function / Type used throughout the program (Enums, etc. not supported yet).
The path finding thing does not work yet, so any test files have to be in the same directory as this document generator.

Sample output from
http://fusionware.ourproject.org/itech/ ... r/test.txt
and its included files can be seen here:
http://fusionware.ourproject.org/itech/ ... t.txt.html

[D.J.Peters]

good work so far
i'm sure after it goes higer than beta the html look will be nicer.
do you like the doxygen colors and style?

Joshy

[KristopherWindsor]

I looked at some of the Doxygen results, but I didn't see a single page to model my program by. I can improve the HTML, but I think the way it reads the code is more important to change right now.
I'm not really sure what to add, so:
- Should the program attempt to find Subs, etc., directly from the source code without needing comments?
- What types of commands should it support in addition to @param and the ones I already have?
- Could someone post an example of an Enum and [De]Constructor so I know how to implement them?
- Should I attempt to create pictures showing the Sub / Function calls?
- I still need a list of the paths where .BI files might be.
- Should I make each Sub / Function / Type in the documentation link to a separate file that shows the Sub / Function / Type in HTML with syntax highlighting?
- Should I replace "@" with "=" so you don't have to press the Shift key?

:-)

[VonGodric]

I while ago I worked on a documentor plugin for future version of fbide. The way I did was to actually parse source code. comments added additional information about particular peaces of code.

Also my implementation bulit an xml file containing structure and using this xml tree it's possible to build any target documentation (html, pdf, ...)

But it's not complete so...

anyway documentation generators and doc style should look & feel natural. Meaning that there is no need to document parts taht parser can find out on it's own - like return types, arguments, namespaces and such. The less "keywords" the better as well. You could take a look also at D language documentor http://www.digitalmars.com/d/ddoc.html

[D.J.Peters]

Hello KristopherWindsor
what are the last version of your FreeBASIC source code doc creator?

Joshy

[KristopherWindsor]

Hello KristopherWindsor
what are the last version of your FreeBASIC source code doc creator?

Joshy

Sorry, I haven't worked on it recently. :-|
I'll put it on my list of ten things to do, but I haven't had much time recently with college. ;-)