Replies: 9 comments
-
You are right, OW doesn't use any type of documentation included into code. |
Beta Was this translation helpful? Give feedback.
-
Doxygen supports most of those formats and more: https://www.stack.nl/~dimitri/doxygen/manual/output.html The problem is that, as a new contributor, I find it hard to navigate through hundreds of files, each thousands of lines long, without any sort of code documentation. Given the contrived and low level implementation of some parts, this is rather a slow process. I have then started commenting some parts of the code in order to make my life easier. |
Beta Was this translation helpful? Give feedback.
-
WGML is a markup language from which all of Open Watcom's documentation is generated, and it's rather simple. If you look in the docs/doc directory, you'll see a whole pile of .gml files that represent the documentation source. You do not need the help compiler to build the documentation. You should be able to build, for example, the PDF manuals without it. Alternatively, you can use Free Pascal's chmcmd, which works like a dream on all OW-supported platforms. I'm not sure if adding doxygen comments everywhere is the best plan since it would dirty up the commit record. I would suggest either a "add as you go" strategy or creating a branch for a larger addition of doxygen comments and squashing to a single commit prior to submitting a pull request. Those are merely my opinions, though. One fun project would be a doxygen backend that produces valid WGML! It'd be useful only to this project, but it would certainly be interesting! |
Beta Was this translation helpful? Give feedback.
-
@ArmstrongJ the "add as you go" is what I was suggesting, as to make any changes in the source I need to figure out what some parts of the code are doing anyways. I certainly would have loved if someone before me took a bit of time to document the source. The backend would certainly be a possibility for the future! |
Beta Was this translation helpful? Give feedback.
-
I'm generally in favor of the idea of adding doxygen comments to the source. They would provide a level of documentation currently not covered by the WGML documentation set... and that would be awkward to write and maintain in "external" files in any case. As far as adding doxygen comments in separate commits go, I'm not sure I agree that would be a good approach. Documentation shouldn't be treated as second class compared to the code. The kind of comments doxygen encourages are an integral part of the program in my view and should be committed alongside corresponding code changes as appropriate. |
Beta Was this translation helpful? Give feedback.
-
I have been using SlickEdit for years. It scans all the source tree in the background and displays classes, functions, macros, including the comments added on the source files. It also displays all the places where a function is called (references). It has single-key compile and build for Watcom (SlickEdit version 7), invoking your makefile. Given a class, it displays all the derived classes, no matter where are they located. |
Beta Was this translation helpful? Give feedback.
-
Microsoft help appears to no longer be available at the links provided in howto.txt:
No longer true. Both links appear to be broken. I want to do a full build. Can anyone provide me with a link to the Windows Help Compiler? |
Beta Was this translation helpful? Give feedback.
-
I added installation package of Microsoft Help Compiler to OW tree Microsoft Help Compiler |
Beta Was this translation helpful? Give feedback.
-
could also use cccc.exe its been a part of the codeblocks compiler for some time, and spits out formatted html pages with build tree, classes, comments and the works. Also its a single executable, so one could do automated code documentation on the fly :) |
Beta Was this translation helpful? Give feedback.
-
I am wondering whether OW generates documentation for the code (structs, macros, functions etc) in any way.
I haven't built the documentation as I can't seem to find a version of the Windows "Help Compiler" (hcrtf.exe), but the howto.txt doesn't seem to imply that there is any sort of code documentation.
If no documentation is available, I would like to know if anyone would be against me adding doxygen comments to some parts of the code.
Beta Was this translation helpful? Give feedback.
All reactions