Páginas

▼

domingo, 6 de noviembre de 2011

Generador de Documentacion para Gambas2 y Gambas3: Front-End para RoboDoc

Generador de Documetación para Gambas2 y Gambas3
Un Front-End para RoboDoc

Cuando conocí java, también encontré a javadoc (no confundir con gambadoc), un generador de documentación que analizaba el código fuente y los comentarios para crear la documentación del programa.

He estado buscando un programa, similar, para que hiciera esa tarea con nuestras aplicaciones realizadas con gambas2 o gambas3, y revisando el cuadro de la wikipedia de generadores de documentación, encontré a RoboDoc. (He traducido (con google traduce) al castellano el manual de instrucciones  enlace )

Para poder usarlo con los proyectos de gambas, este programa hay que crear un archivo robodoc.rc.

 Ejemplo de configuración realizada:
headertypes:
P "Procedure" robo_procedure
E "Events" robo_event
header markers:
'****
remark markers:
'*
end markers:
'****
  ( En el FrontEnd que he realizado, ademas se ha añadido la serie de palabras claves para Gambas2 y Gambas3, que no lo pongo aqui porque es muy extensa).

He creado este Front-End (que añade este archivo de configuración) para que podamos usar RoboDoc, y que nos cree la documentación de nuestros proyectos Gambas.


Programa Ejecutable: FrontEndRoboDoc002.83.gambas [version 0.0.2]
Código Fuente (no ejecutar): frontendRoboDoc-0.0.83.tar.gz [version 0.0.2]

Nota Importante:
Es una beta, usarlo con cuidado, hacer copias de seguridad de vuestros proyectos antes de ejecutar el programa.

Podeis ver este video para ver como se utiliza:



El programa crea una nueva carpeta (Hdoc) dentro de la carpeta de nuestro proyecto, y alli podemos encontrar los archivos .html (si hemos elegido la opción de tipo html).

Os dejo aqui un archivo para que veas como hay que "codificar" los comentarios y para ver el resultado en html obtenido por RoboDoc, ver este enlace (ficheros html)


Captura de Pantalla:
Código que la genera:
'****h* Clases/Tableview
'****
'****h* Tableview/Definicion
'* FUNCTION
'* El Control Tableview
'* http://www.gambas-es.org/el-control-tableview-vf4-vt37.html
'* SYNOPSIS
'* Mejora del gridviews, para hacerlo editable
'* INPUTS
'* Hereda de un gridview
'* RESULT
'* Retorna un control gridviews editable
'* SOURCE
' Codigo fuente '
' Gambas class file '
' hereda del control Gridviews '
INHERITS GridView
' la clase se exporta: Esto significa que la clase será visible desde un programa principal cuando creemos un componente. '
EXPORT
' Creamos nuevos eventos o sustituyen a otro ya definido '
EVENT Save(Row AS Integer, Column AS Integer, Value AS String)
EVENT Insert
EVENT Click
' creamos controles auxiliares '
PRIVATE $hTextBox AS TextBox
PRIVATE $hComboBox AS ComboBox
' objeto hEditor: es un objeto que podra ser un combobox o un textbox... '
PRIVATE $hEditor AS Object
PRIVATE $bTextBox AS Boolean
PRIVATE $iCol AS Integer
PRIVATE $iRow AS Integer
' Objeto Watcher: Esta clase implementa un Objeto que puede ver cualquier tipo de control y crear algunas situaciones '
' cuando algo sucede en él. Esta clase es especialmente útil para saber cuando un UserControl o UserContainer se mueve, cambia de tamaño, mostrar u ocultar. '
PRIVATE $hWatcher AS Watcher
'****
'****m* Tableview/Constructor de Tableview
'* FUNCTION
'* Construye el tableview
'****
'constructor.....
PUBLIC SUB _new()
DIM hObs AS Observer
' llama al observador y al wacther como nombre del grupo "GridView" '
hObs = NEW Observer(ME) AS "GridView"
$hWatcher = NEW Watcher(ME) AS "GridView"
$hComboBox = NEW ComboBox(ME.Window) AS "Editor"
$hComboBox.Ignore = TRUE
$hComboBox.Hide
$hTextBox = NEW TextBox(ME.Window) AS "Editor"
$hTextBox.Ignore = TRUE
$hTextBox.Border = FALSE
$hTextBox.Hide
END
'****m* Tableview/SaveEditor()
'* FUNCTION
'* Guarda en la celda lo editado
'****
PRIVATE SUB SaveEditor()
DIM sText AS String
IF NOT $hEditor THEN RETURN
sText = $hEditor.Text
IF sText = ME[$iRow, $iCol].Text THEN RETURN
' Raise: Esta orden dispara un evento antes declarado con la palabra clave EVENT. '
RAISE Save($iRow, $iCol, sText)
' refresca la celda.. '
ME[$iRow, $iCol].Refresh
END
'****m* Tableview/Save()
'* FUNCTION
'* Oculta el editor.
'****
PUBLIC SUB Save()
HideEditor
END
'****m* Tableview/Cancel()
'* FUNCTION
'* Cancela la edicion
'****
PUBLIC SUB Cancel()
HideEditor(TRUE)
END
'****c* Tableview/HideEditor()
'* FUNCTION
'* Oculta el editor.
'* RESULT
'* Retorna el editor, como oculto y null
'****
PRIVATE SUB HideEditor(OPTIONAL bNoSave AS Boolean)
IF $hEditor THEN
IF NOT bNoSave THEN SaveEditor
$hEditor.Hide
$hEditor = NULL
ENDIF
END
PRIVATE SUB MoveEditor()
DIM X, Y AS Integer
IF NOT $hEditor THEN RETURN
' determina posicion del editor text '
X = ME.ScreenX - ME.Window.ScreenX
Y = ME.ScreenY - ME.Window.ScreenY - ME.Window.ClientY
'DEBUG $iRow;; $iCol
' Mueve el objeto $hEditor, a la posicion de la celda (x,y, y su ancho y altura) '
WITH ME[$iRow, $iCol]
X += .X
Y += .Y
$hEditor.Move(X, Y, .Width, .Height)
END WITH
'DEBUG
$hEditor.Font = ME.Font
$hEditor.Show
'DEBUG
END
PUBLIC SUB GridView_MouseDown()
HideEditor
END
PUBLIC SUB GridView_RowResize(Row AS Integer)
HideEditor
END
PUBLIC SUB GridView_ColumnResize(Column AS Integer)
HideEditor
END
PUBLIC SUB GridView_Scroll()
HideEditor
END
PUBLIC SUB GridView_Resize()
HideEditor
END
PUBLIC SUB GridView_Hide()
HideEditor
END
PUBLIC SUB GridView_Change()
HideEditor
END
PUBLIC SUB Edit(OPTIONAL List AS String[], OPTIONAL ReadOnly AS Boolean)
' DEBUG '
HideEditor
$iCol = ME.Column
$iRow = ME.Row
IF $iCol < 0 OR $iRow < 0 THEN RETURN
IF List THEN
$hComboBox.List = List
$hComboBox.ReadOnly = ReadOnly
$hEditor = $hComboBox
$bTextBox = NOT ReadOnly
ELSE
$hEditor = $hTextBox
$bTextBox = TRUE
ENDIF
$hEditor.Text = ME[$iRow, $iCol].Text
TRY $hEditor.SelectAll
MoveEditor
$hEditor.SetFocus
END
PUBLIC SUB Editor_Activate()
SaveEditor
END
PUBLIC SUB Editor_Click()
SaveEditor
END
PUBLIC SUB Editor_KeyPress()
SELECT CASE Key.Code
' pulsa la tecla Esc '
CASE Key.Escape
$hEditor.Text = ME[$iRow, $iCol].Text
STOP EVENT
' pulsa la tecla Flecha hacia arriba '
CASE Key.Up
WHILE ME.Row > 0
'DEC: quita 1 unidad.
DEC ME.Row
RAISE Click
IF $hEditor THEN
STOP EVENT
BREAK
ENDIF
WEND
' pulsa la tecla Flecha hacia abajo '
CASE Key.Down
WHILE ME.Row < (ME.Rows.Count - 1)
' INC: incrementa 1 unidad '
INC ME.Row
' Esta orden dispara un evento antes declarado con la palabra clave EVENT. En este caso el Click '
RAISE Click
IF $hEditor THEN
' para el evento '
STOP EVENT
BREAK
ENDIF
WEND
' pulsa la tecla Flecha hacia izquierda '
CASE Key.Left
IF $bTextBox AND IF $hEditor.Pos > 0 THEN RETURN
DO
IF ME.Column > 0 THEN
'DEC: Decrementa una variable. (le quita 1)
DEC ME.Column
RAISE Click
ELSE IF ME.Row > 0 THEN
ME.MoveTo(ME.Row - 1, ME.Columns.Count - 1)
RAISE Click
ELSE
BREAK
ENDIF
IF $hEditor THEN
TRY $hEditor.Pos = $hEditor.Length
STOP EVENT
BREAK
ENDIF
LOOP
' pulsa la tecla Flecha hacia la derecha '
CASE Key.Right
IF $bTextBox AND IF $hEditor.Pos < $hEditor.Length THEN RETURN
DO
IF ME.Column < (ME.Columns.Count - 1) THEN
INC ME.Column
RAISE Click
ELSE IF ME.Row < (ME.Rows.Count - 1) THEN
ME.MoveTo(ME.Row + 1, 0)
RAISE Click
ELSE
BREAK
ENDIF
IF $hEditor THEN
TRY $hEditor.Pos = 0
STOP EVENT
BREAK
ENDIF
LOOP
' pulsa la tecla Enter o Return '
CASE Key.Enter, Key.Return
IF $bTextBox THEN
DO
IF ME.Column < (ME.Columns.Count - 1) THEN
INC ME.Column
RAISE Click
ELSE IF ME.Row < (ME.Rows.Count - 1) THEN
ME.MoveTo(ME.Row + 1, 0)
RAISE Click
ELSE
RAISE Insert
STOP EVENT
BREAK
ENDIF
IF $hEditor THEN
TRY $hEditor.Pos = 0
STOP EVENT
BREAK
ENDIF
LOOP
ENDIF
END SELECT
END
'****h* Clase/SegundaClase
'* FUNCTION
'* Viendo la cabecera de SegundaClase clase
'****
'****h* SegundaClase/Definicion
'* FUNCTION
'* Esto es una comprobacion de clase
'* http://www.gambas-es.org/el-control-tableview-vf4-vt37.html
'* SYNOPSIS
'* Mejora del gridviews, para hacerlo editable
'* INPUTS
'* Hereda de un gridview
'* RESULT
'* Retorna un control gridviews editable
'****


Espero que os resulte util.

Nota:
Estoy trabajando en un programa que "lea" el codigo fuente y crea el 80% de los comentarios necesarios para RoboDoc, asi sera mucho mas facil (y menos trabajoso) añadirles los comentarios.
Ver este enlace: mapcomen-generador-de-comentarios


Notas:
21/nov/2011: corregido bugs cuando fallaba la copia del icono.
13/nov/2011: Las descargas estan actualizadas a la version 0.0.2.
Se le ha añadido la impresión en la documentación del icono y titulo del proyecto
21/nov/2011: corregido bugs cuando fallaba la copia del icono.
en