JacquesCarette
Create Documentation Map for drasil-gool Directory
Based on yesterday's meeting, I thought about creating a documentation map for the [drasil-gool] directory to improve understanding and maintainability of the codebase. This map will outline the purpose and functionality of each file in the directory, providing a brief description of what each file is used for and highlighting its key components or features. The goal is to make it easier for new contributors and developers to navigate the [drasil-gool] codebase. Once completed, the documentation map will be added to the repository in an accessible location, such as the wiki or as part of the README. This will serve as a helpful reference for anyone working on [drasil-gool] and contribute to better overall project documentation.
Excellent idea! Doing it on the wiki, and then having the documentation (README, probably inside the code too) point to that might give you more freedom. We'll want @B-rando1 to review, and even @bmaclach might be interested too.
I've finished the graph and would appreciate reviews and feedback to clarify any potential misunderstandings.
Looks very nice indeed. The central stuff seems right.
Some of the 'utilities' on the left are much more than that, and contain crucial information defining some of the basic data-structures in use throughout.
You'll probably want to change the terminology -- some are helpers, others something else. So that left box may need to be split into 2.
Thank you @JacquesCarette for the clarification. Here's a second version. I don't know why the quality drops after I download the pdf.
If you view it at its "native" size, the PDF is fine. My guess is that it is using bitmaps instead of proper fonts. I guess it depends on how you did the export from the tool you're using.
I'm realizing that it's been a while since I've looked at GOOL 😅
I think you've got the right idea, though. There's the external typeclasses in the InterfaceX files, the internal (technically optional I believe, but useful) typeclasses in the RendererClassesX files. There's the AST, Classes, CodeAnalysis, CodeType, Helpers, LanguageRenderer, and State files that provide lots of different functionality, some of which is used by most or all renderers, some of which is used by only one or two. I wish I could give more information on these, but I'd need to spend more time looking at them. The CodeInfoX files implement the external interface, but instead of rendering programs they generate metadata for the renderers to use.
Within the LanguageRenderer folder, there's a bunch of shared rendering files: AbstractProc, CLike, CommonPseudoOO, Constructors, LanguagePolymorphic, and Macros. These are used by the actual renders for the 6 languages we support, which utilize various bits of functionality from other files to produce the final output programs.
I'm not sure how useful this is, since most of it's in the wiki anyway, but hopefully it's a good confirmation. Anyway, I think what I've said here matches what you have, for the most part at least.
Always happy to see someone working on GOOL :)
I took a look at both documents, and they seem accurate to what I remember (I also have been a long time away from GOOL, though). A few things jumped out at me:
- The absence of the language specific renderer implementations in the graph seems notable (JavaRenderer.hs, CppRenderer.hs, etc). I think these belong in the "Language Renderers" box as they are the modules that actually implement both the "External Interface Layer" and the "Renderer Interface Layer"
- I was surprised that the description of CodeAnalysis.hs was so focused on exceptions. Looking at the file, the description is accurate, but I suppose the purpose of the file is to hold types and helpers used by the
CodeInfoimplementations, and it just so happens that so far we have only needed types and helpers related to exceptions. - The description of Classes.hs speculates on the utility of the Pair typeclass, and I can shed a little more light on this. I recall that it is primarily used for the C++ renderer, to "pair" together the representations of C++ source file code and C++ header file code. (more generally, it would be used for any language renderer that requires multiple representations for the same code)
