tajmone
commented
5 years ago Ciao Thomas!
It would be nice with a brief explanation of the main differences, philosophical and/or practical, between doxter and other tools with similar intent, such as Doxygen.
I haven't a practical experience working with Doxygen, but before embarkng on the creation of Doxter I had looked into various doc generators (including Doxygen), and ultimately decided I wanted to create a custom tool taylored to my needs.
Among my main goals, I wanted a tool that:
- Relied on a single standalone binary file, no dependcies, and cross platform. I wanted the tool to be free from any constraints of scripted languages versions or thirdy party tools — so that a copy of the binary tool could be left in the folder of a project, regardless of latest versions of the tool.
As for the actual documentation system, Doxter is based on some dimplr guiding principles:
-
The comments "markers" system must rely on non invasive symbols that blend in with the source code without making it hugly.
- It should be a language agnostic tool, with no expectations in terms of functions, data types, etc.
Matter of factly, the only requirement is that the source files have a single line comment delimiter, it doesn't have to be a programming language at all (it could be a markup language too).
But what I consider makes Doxter different is that it allows to easily control how the extracted documentation is re-arranged in the output document. What I realized is that the code has its own order, and I wanted to keep each chunck of documentation next to the code it belongs to, but at the same time produce documents in which I could control the order in which each chunck is rearranged.
This is when I realized that leveraging AsciiDoc would be the obvious choice, since Asciidoctor has this great feature of tagged regions which can be selectively included by other documents. So I thought:
- I need a tool that leverages a prexesting lightweight markup syntax, possibly more powerful than markdown — which better choice than AsciiDoc?
- Doxter's sole function is to allow users to mark the beginning and end of tagged regions:
- Regions can contain both source or pure AsciiDoc lines.
- AsciiDoc lines are comment lines beginning with a special marker.
- Each region can be assigned a tag, a weight and a subweight (all of them optional):
- Same named region fragments are merged together into a single AsciiDoc tagged region before the document is created.
- Before merging regions fragments, all fragments are sorted by their subweight (allowing control over contents arragement).
- And different regions are also rearranged according to their weights.
After a few tests I realized that this system is easy to use, looks clean in the source code, has high portability potential across different languages and, most of all, it allows me to control documentation in a specific way:
- From each source file (eg, a module) Doxter will extract a full document for that module.
- I can then create indepent ADoc document(s) for the whole project, and import selectively tagged regions from the autogenerated ADoc files. This means that I can create a full book that imports spefic paragraphs (regions) direcly from the source files, so the book contents will automagically be always up to date with source files.
Basically, it's a simple way of keeping the core information in the source files, and the at the same time have a lengthier documentation outside the source files, but still relying on them for key aspects. It also means that actual code examples (eg, Alan demos) can use Doxter regions and become part of the final documentation. So you end up having a documentation that feeds off not only the source files of the library, but also from its examples and test files, effectively making it easy to avoid redundant efforts — source comments are one and all with the project's book, the module's specs documents, examples and even (possibly) a Wiki adn website, for every document is importing from the others.
This cross reference system allows library comments to quickly include a full example file with a single AsciiDoc directive, and in the final doc you'll find the full source of the example, as well as the documentation of the example itself.
Obviously, this might not be everyone's need. I've started creating Doxter for PureBasic, which doesn't integrate well with other docs generators; but then I ended up using it with the Alan Library project. Doxter is still young, and I have quite a few features in mind which I want to add. But right now I'm using it everyday, so I can get a need-based feel of where to go next.
Tonight I'll create an Alpha release in the repo, so I can attach a zip file with precompiled binaries. I only need to retouch the license for the binary distribution, to include the licenses of all third pary component that end up in the compiled version.
I'll buzz you when the binary is online, so you might give it a go yourself.
But I also advise you to look at the Italian Library source files, and the generated documentation. Although I haven't yet got as far as creating a whole book from these source, I've at least managed to create self-updating documents for each module:
Specifically, the verbs and definitions modules are those which I've been working more:
and:
You can easily see how Doxter markers blend with the code, and how elements which are continguos in the source file are grouped differently in the output.
That would make it easier to select between them for my next project ;-)
Well, you are the only one who can decide on that. Probably much depends on what type of documentation you need to produce, and what features you're looking for. Obviously, Doxygen is a solid product with a large community. On the other hand, Doxter relies on AsciiDoc, which is a well established syntax, with greater potential than markdown for documentation (and also covers more output formats).
T.
It would be nice with a brief explanation of the main differences, philosophical and/or practical, between
doxterand other tools with similar intent, such as Doxygen.That would make it easier to select between them for my next project ;-)