Documentation Tool
-
So when I first got my current job, I was tasked with finding a documentation tool for our React app (which uses typescript).
I was unsuccessful in this regard, and decided I don't want to add a package that might do it because, well, we already have a bazillion packages that we have to keep on top of in terms of versions (we can't be more than one major revision behind the latest available). So I came up with my own (that is still under development.
It's written in C# and it's (minimal) interface is WPF, and it's nowhere near complete, but here's some of the stuff it currently does:
-
It generates a series of HTML files in the same folder hierarchy as the project being documented. Generally you get one HTML file for the documentation, and one that shows the syntax-highlighted source code, and the documentation HTML has a link to the source code HTML file
-
Creates one HTML file for every source file (.js, .ts, .tsx, .md)
-
Creates property lists for interfaces, classes, types, and enums, including their comments and default values (if any)
-
cross-links types/interfaces/enums so if you click one, it takes you to the html file where that item is implemented.
-
in source file html, it allows you to filter what's displayed so you can choose to only any combination of interfaces, functions, exported/not exported, etc
-
shows non-exported items in a dimmer visual style
-
Displays the imports in a collapsible accordion (in the interest of completeness of documentation).
-
If no type is specified for parameters or functions that return a value, the tool assumes and indicates "any" (and indicates that the type has been "interpolated", illustrating a possible shortcoming of the code).
-
It expects the standard (?) "/** */" comment style, and will look for that in all properties and functions.
I've also started allowing it to parse component functions into their own HTML files. A "component function" is determined by the return type, so it relies on the programmer to actually specific a react component return type, such as JSX.Element, ReactNode, or some other identifiable type.
This means the programmer is responsible for the quality of the generated documentation by way of adequate/suitable comments and type specifications. Not having this stuff won't keep the tool from working, but it WILL keep the tool from generating decent documentation, making it a true "garbage in, garbage out" representation of the project.
Finally, this tool generates the documentation on demand, and for my current project of about 850 source files, it takes about 6 seconds to generate about 1700 files. The files are presented from a main index file with a tree on the left side, and files selected there are displayed in a new tab in the browser window.
It looks like we can add images to messages, so I'll add some screenshots when I get home from work.
BTW, I posted a demo video on Youtube, but we can't use youtube from work, so I have to get the link from home as well, but if you're interested, look for the "realJSOP" user. The demo video is kinda old (months old) and I've fixed any probs that might be evident since it was made, but you'll get an idea of where it's going. I'm gonna make another video here in the next week or so.
-
-
This is the generated index file. The info being displayed on the right side comes from the App.md file and for this project, is only to demo the ability for the doc tool to generate html for a .MD file. The tree on the left is for browsing the files generated by the tool.
-
Here's a shot showing a file that was selected from the tree. Clicking on a file opens the selected file in a new tab. You can see the link to browse the actual source file, as well as three drop-downs:
"Show these items" - allows you to filter what part of the source documentation is displayed (constants, functions, hooks, etc, as well as whether to display exported, non-exported or both.
"Notes" - this is an accordion that displays metrics gathered during the parsing action, as well as notes about doc tool notes regarding how to read the page.
"Imports" - this is an accordion that displays the imports from the parsed file. The next screen shot will show these accordions expanded.
-
The following illustrates documented items from the source file, as well as the visual difference between exported and non-exported items. If you see the term "any (interpolated)", it means that the programmer neglected to specify a type, and is a visual way of identifying where the code may need to be modified to satisfy a truly type-safe use of typescript.
All property and parameter definitions are parsed from the source file, which means your resulting documentation will only be as good as your commenting efforts.
-
-
It's still a work in progress, and there are currently some minor issues I have to fix, as well as finishing the parsing of component functions (into their own files because components can be really huge in their own right).
I haven't worked on it in a month or so because I'm working on the React app I use to test the tool (no better test than a real app), but I'll eventually get back to it.
The cool thing is that there are over 200 files, and it only took six seconds to generate the complete set of doc files. Because you actually have to generate the files with this tool, it's a simple matter to "catch-up" your existing docs by simply running the tool again. I think that's pretty cool.
