Natural Docs 2.1 beta 1
October 6th, 2020

Time to wrap up the pre-releases.  I consider 2.1 done, I'm just going to release it as a beta for a month to see if anyone finds any bugs before rechristening it 2.1 proper.  So what's new?

Image Support

I finally finished image support, which was the biggest thing missing from 2.0 that was in 1.5.  To refresh your memory on how it works, you just add (see filename.jpg) to a comment.  There's two ways to do it:

// If you put it in the middle of a paragraph like this (see logo.png) it will
// become a captioned image after the paragraph.
// If you give it its own paragraph like this, it will simply be replaced by
// the image.
// (see logo.png)
// It needs to be separated from other paragraphs by blank lines.

You can use PNG, GIF, JPG, SVG, and BMP files.  You can include part of a path, such as (see images/diagram.svg).  By default this is relative to the source file the comment appears in, but you can also specify image folders in Project.txt and on the command line with -img.  It will search all these locations when looking for the image.

Minor Improvements
  • Improved documenting parameters in PHP.  Optional types wouldn't be pulled from the prototype into the documentation correctly before.

  • C/C++ structs get prototypes now.

  • Rebuilding is smarter.  Changing Languages.txt or Comments.txt causes all the source files to be reparsed but it won't rebuild all the output, only the output of the things affected by the changes.  Running Natural Docs with --rebuild-output will now do only that without also reparsing unchanged source files.

  • Fixed some issues merging multiple source files into a single class view when there were three or more of them.

  • Fixed some obscure crashes.

Behind the Scenes

I finished the change management refactoring I started earlier, this time doing the HTML generation code.  It took a lot longer than anticipated but now it's much cleaner with better separation of duties, which in turn made adding image support much more manageable.  I'm hoping it will continue to pay off like that going forward.  I don't think people realize how involved it can be to keep Natural Docs' build process differential.  If it was rebuilding the entire documentation set on every run it would be easy, but if you only want to update the things that changed you have to be able to track every dependency and cascading effect every potential change has.  It makes it harder to write but so much faster to run, which allows you to continuously update your documentation as you work.

I'm confident in this release and was very tempted to call it 2.1 Release Candidate 1.  I'm not planning on any more changes except bug fixes.  All new features are going into 2.2 instead.  The scope of the internal changes just made me decide to treat it as a beta for a month before finalizing it.

Earlier Discuss Share Later
Natural Docs 2.1 development release 2Natural Docs 2.1 beta 2
FacebookTwitterE-MailCopy Link