Everybody knows it. Documentation is essential. Most people hate two things about it. The first one is to create it, the second to read it.
The Java community has JavaDoc. This takes care of both objections. Generate the documentation so you don’t have to write it. You still have to read it, there’s no shortcut here however JavaDoc is fairly straightforward to use, easy to navigate to the area of interest and this helps you locate that piece of documentation you need.
That’s all nice for the Java community, what about us Oracle Forms Developers? There’s FoReDoclet.
FoReDoclet can generate HTML documentation for Oracle Forms. It includes the form, menu, PL/SQL library and object library.
Comments you write while creating your Form will be included in the generated documentation. For Program Units you can include comments not only in the Comments-property, but also in PL/SQL Editor.
Whether you use single-line comment (--), or multi-line comments (/*...*/) it doesn’t matter, FoReDoclet takes care of it. To make things even more flashy, you can even use HTML in your comments.
What about the “regular” JavaDoc tags like @author, @version or @throws? FoReDoclet does support the @throws tag, others are simply omitted from the generated documentation. FoReDoclet will show the exceptions you specify in the @throws-tag in the exception section of the generated documentation.
For those of you unfamiliair with the @throws tag, the “documentation-generator” will interpret these as possible exceptions which the program unit can “throw back” at you.( In the “civilized” Oracle world we don’t throw things, we raise them ;-)).
Talking about making things flashy, it’s possible to include screenshots in the documentation. It’s a nice feature, will it be used in a production-enviroment? I doubt it., but it looks great.
To see a full fledged example take a look at this.
FoReDoclet is very flexible, it allows you to filter for specific forms, menu etc. These filter options are also generated in the documentation. The look and feel of the documentation can be modified to suit your needs. Inclusion of company-logo, application-logo or module-logo is all part of the deal.
Even though FoReDoclet is open source, it doesn’t include any documentation on it’s use. However you can purchase documentation. It’s available through their website.
Using FoReDoclet to create documentation will be a breeze and is fun to do….
in addittion to Scuba, i did an unconventional step I copied the frmjdapi.jar from ~IDS/java path to the ~FoReDoclet/lib path and I have it working now.
thx Scuba
I finally got around the jdapi error by setting the oracle home and path:
I also used a newer pldoc since I had that installed too.
Â
@ECHO OFF
set ORACLE_HOME=C:\DevSuiteHome_1
set PATH=%ORACLE_HOME%\bin;%ORACLE_HOME%\jdk\jre\bin;%ORACLE_HOME%\jdk\jre\bin\classic;%ORACLE_HOME%\jlib;%ORACLE_HOME%\jdk\bin;%PATH%
REM Resolving the directory of foredoclet
set frddir=%~d0%~p0
set clpth=%frddir%;
set clpth=%clpth%%frddir%lib\castor-0.9.4.2-xml.jar;
set clpth=%clpth%%frddir%lib\cryptix-jce-api.jar;
set clpth=%clpth%%frddir%lib\cryptix-jce-provider.jar;
set clpth=%clpth%%frddir%lib\cryptix-message-api.jar;
set clpth=%clpth%%frddir%lib\cryptix-openpgp-provider.jar;
set clpth=%clpth%%frddir%lib\cryptix-pki-api.jar;
set clpth=%clpth%%frddir%lib\dom.jar;
set clpth=%clpth%%frddir%lib\foredoclet.jar;
set clpth=%clpth%%frddir%lib\jaxp-api.jar;
set clpth=%clpth%%frddir%lib\log4j-1.2.7.jar;
rem set clpth=%clpth%%frddir%lib\pldoc-0.7rc1.jar;
set clpth=%clpth%%C:\Support\Documentation\pldoc-0.9.0\pldoc.jar;
set clpth=%clpth%%frddir%lib\sax.jar;
set clpth=%clpth%%frddir%lib\velocity-dep-1.3.1-rc2.jar;
set clpth=%clpth%%frddir%lib\xercesImpl.jar;
set clpth=%clpth%C:\DevSuiteHome_1\forms\java\frmjdapi.jar;
set clpth=%clpth%%frddir%lib\jakarta-oro-2.0.6.jar;
set clpth=%clpth%%frddir%lib\IzPress.jar
set
java -Xmx512M -cp “%clpth%” nostran.foredoclet.DocSession %* “-foredoclet.homedir=%frddir%”
Hi Antonio,
Sorry, can’t help you there (haven’t used it in 6 years). But on the FoReDoclet page you can submit a bug report:Â http://foredoclet.sourceforge.net/products/foredoclet/bugPage.htm
Please helpme, I tried install, 1.1 version, but send me error with autorun.vm.. this file not exists…
Hi all,
I’m testing this product using client configuration as point 19. It’s working fine but I ‘ve still problem reading PLSQL Code from my forms such as sample forms (core.fmb).
DEBUG nostran.foredoclet.util.TemplateHelper – DEBUG WARNING: A package body was tried to be parsed (unknown PL/SQL object type)
appears in foredoclet.log file.
Any ideas?
It’s been quite a while that I have used this tool, in fact I have changed laptops since and haven’t installed it on my “new” machine – which is due for replacement soon. You can’t deinstall it the regular way you deinstall Windows applications?
this tool is throwing errors for me…
any idea how to de-install?
thanks in advance.
hi Nilesh,
FYI…
The jdapi.jar file name varies from version to version.
For oracle forms version – 101202, the name is “frmjdapi.jarâ€, in the same way search
for this file for other versions in the folder where oracle forms installed.
Ex : in my machine oracle forms has been installed in the path of
” D:\DevSuiteHome_1\forms\java\frmjdapi.jar “.
Have you selected the same path while installing FoReDoclet tool? If not please do that it will solve many problems…:-)
I am not aware of GAFORMS.fpp file and no other setup has been done my side while i was using this tool.
Thanks,
Supriya
Hi Alex,
Thanks for the reply. I got the answers for my questions after some investigation. ForDoclet 1.1 got worked on the below versions.
oracle database – 10201
D2K – 101202
Java Runtime Environment – 1.4.2
Only point to remember is fordoclet installs only the folder (with some sample projects) in whatever the path we give at installation time.everything has to process from this folder.
anyway i need one more information on this.
Is tehre any competitor tools available in market for this FoReDoclet Tool?
Thanks,
Supriya
Supriya,
From what I understand from the Sourceforge page, is that FoReDoclet only works with Forms 6 and 9. And you would have a newer version, so it would appear you’re out of luck.
The last update to the SourceForge page was done in 2006, more than 3 years ago…
Hi,
I installed following softwares in my machine to work with foredoclet.
oracle database – 10201
D2K – 101202
Java Runtime Environment – 1.4.2
and then tried to install ForeDoclet – 1.1
followed the below steps for the same
1)Downloaded set-up.jar file and foredoclet-sources.zip
2)Run the set-up.jar file and it was asked for “F90JDAPI.jar ” file.
This jar file i find in foredoclet-sources.zip but not in oracle home. I selected this and continued withthe installation.
got the message of installation finished and i clicked on quit button.
Hmm…but nothing has been installed related to Foredoclet.
Could anyone help me in this installation process?
Thanks in advance
-supriya
Hi Nilesh, Thank you for your comments.I’m not familiar with the GAFORMS.fpp file, Maybe the comment by Lucas (comment #3) can help you on the way.
I installed foredoclet but when i am trying to execute it it is showing error that “didn’t find f90jdapi.jar file”
I have changed path of f90jdapi.jar file in GAFORMS.fpp but it is still showing error
OK Alex. 🙂 Thanks. (Y)
Hi João,
Thank you for your comments. I’m sorry but I can’t help you with this. Maybe the comment by Lucas (comment no.3) might give you some clues.
Alex
btw. Mr. Nuijten is my father, just call me Alex 🙂
Mr. Nuijten,
I hope that you can help me…
When I’m trying to execute the FoReDoclet application, I got the following error:
————————————————————-
FoReDoclet Version 1.1.7
Initialising…
Profile name: C:\FoReDoclet\sampleProject\core_techDocs.fpp
Output directory: C:\FoReDoclet\sampleProject\output_core
Home: C:\\FoReDoclet
Initialised.
————————————————————-
Parsing documentation profile: C:\FoReDoclet\sampleProject\core_techDocs.fpp
Parsing extraction template: DEFAULT
Creating the repository
ERROR: During the creation of the source repository.The f90jdapi.jar library might be missing or other Oracle Forms installation/configuration problem.
I don’t know what is wrong, because the f90jdapi.jar is set on the classpath, as the other jars…
I hope that you answer me, as soon as possible.
Thanks.
Hi,
I’m looking at FoReDoclet and I would know if it’s possible to include the code of triggers, program unit… in the generated html documentation and how it do?
thanks
Good
48 hours? You should live in my country and find out what NOT having $50 U.S. to spend it in buying some documentation is not even a choice.
Would you mind explaining how to acomplish its installation? Please
Who ever thought that 48 hours could take so long? 😉
I just received the documentation from nostran company, with an apology for slow delivery.
My trust in mankind is restored 🙂
Warning:
I recently downloaded Foredoclet, i also bought the documentation but alas ….
my creditcard was charged with 50$ but no documentation (i payed 2 weeks ago and they
claim to send the documentation in 48 hours).
So beware! Maybe someone else can help me and send the documentation to me. That would
be much appreciated.
I have done some trials with FoReDoclet and it is clear that they use the Forms 9i/10g JDAPI to read the Forms.
Installation was a bit tricky at first: I did not realize that the jar-files was an executable jar-file: I tried unpacking it and went looking for bat-files or executables. So to install: download foredoclet-1.1-setup.jar and execute it! The installer requires you to provide the location for the F90JDAPI.jar (typically in ORACLE_HOME\forms\java). After that, dissect the SampleProject to get going.
Thanks for your comments.
Based on what I could find, it’s written in Java.
According to their website they use the “public libraries of Oracle Forms to parse the binary source files”.
This entails the requirement that Oracle Forms has to be installed in order to use FoReDoclet. It’s said to work with Oracle Forms 9.0 or later, but Forms 6i will work as well. They’re not clear if FoReDoclet works if Oracle Forms 6i is installed. The 6i source can be used in combination with Form 9.0 builder, it will generate a PLG-file (conversion summary) as well.
It takes about 2 seconds per Form module to generate the documentation. Using an XML-file you can modify the profile FoReDoclet has to follow. Here you can filter the forms you want to include in your documentation. Generation is done for all forms (menu, library, object library) that match your criteria.
Looking at this Profile-file, I noticed you can also filter for RDF-files (Reports). So I tried that as well. The Report does show up in the navigation panel, but that’s all. So far it doesn’t support Reports to be included in the generated documentation. Just guessing… maybe in the future. Thinking about it, maybe that’s why they named it FoReDoclet, as in FormsReportsDoclet.
A recification must also be made. The JavaDoc-tags that can be used, also include @param and @return. The thing that threw me of was the way @param works. If there are no parameters in the program unit, the @param-tag is ignored. If there are parameters in the program unit it will look for the appropriate tag and use it.
Great post! Can you give some more details: Do you happen to know in what technology this tool is developed? How does it read the forms – through the C-api, by converting the fmb-files to fmt-format, by using the Java API? Which versions of Forms are supported? How long does it take to process a form? Is processing done in batch on multiple forms in one go?