Natural Docs 2.1 development release 1
March 6th, 2020

Hey, I'm back.  Let's just admit that Natural Docs' development will always come in bursts instead of being continuous, because that's just how my life goes.  But we're in another good period so let's have a release.

Better Support for SQL

Some time ago I set out to improve SQL prototype formatting thinking it would be a quick fix.  Wow, that was a rabbit hole to get lost in.  I ended up having to revamp much of the prototype parsing and formatting code, but now it can handle complex prototypes like this:

I designed it to handle Oracle's PL/SQL and Microsoft's Transact-SQL.  I haven't looked at the other major database engines, do any of them have significantly different syntaxes that I should be supporting?  I'm thinking about things like how T-SQL can have parameter lists without parentheses.

Better Support for Java

Java now has a parser that can handle @annotations, so if one has parentheses it won't get mistaken for the function parameters.  The updated prototype code can handle giving them nice formatting too:

This is good for things like JAX-RS that use it a lot:

Better Support for SystemVerilog

I also added support for parameterized classes that use symbols other than <>, such as SystemVerilog's #().  The parents weren't being detected before, but now that's fixed and the parameters get syntax highlighting as well.

There still isn't support for SystemVerilog without editing Languages.txt, but that's something I'm going to be looking into.

Smaller Things
  • Natural Docs now builds on macOS and Linux.  It still uses msbuild, which should be included in recent versions of Mono, but it detects when it's not on Windows and swaps out xcopy for cp.

  • Natural Docs now builds in Visual Studio 2015.  There was a C# language feature that was only supported in 2017 and higher, but it wasn't important and only used in a couple of places so I removed it.

  • Long prototypes get thin, unobtrusive scrollbars instead of full size ones.  This only happens when it's so wide or the browser window is so narrow that it can't reformat enough to avoid scrolling.  Works in Firefox and Chrome.  Matches the prototype's colors too.

  • Prototype enders now respect the language's case-sensitivity setting.  So for languages like SQL you can just put "IS" and don't have to also put "Is" and "is".

  • Fixed crash when there were errors in multiple config files.

  • Better diagnostic information in errors so things like not having filesystem permissions or using an outdated version of Mono are clearer.  Some distributions have absolutely ancient versions of Mono which will cause Natural Docs to crash.

Under the Hood

There were big internal changes to how prototypes are parsed, represented internally, and formatted in HTML.  As mentioned, this was done to make room for SQL.  For most people they should look and behave exactly the same though.

There's also some internal change management refactoring going on.  Part of the reason image support has taken so long is that tracking everything has gotten unnecessarily complicated, and it was hard to force myself to work on adding another layer to that.  My coding time tends to come in many small chunks these days, and something like that felt like it needed long stretches of uninterrupted time to concentrate.  Refactoring some of the existing code to encapsulate and isolate things better has helped a lot.  You shouldn't see any difference as an end user though.

Because plumbing changes have the potential to introduce bugs, I'm making this a development release.  I believe everything is in a perfectly stable state though so you should have no problem using this for your day-to-day work.  I'm just being cautious.

Going Forward

The current plan is to continue refactoring change management and then take another stab at image support.  After that I want to make further improvements for SystemVerilog and try to make it a first class citizen in Natural Docs.  I'll need some SV users to bounce questions off of though, so if anyone wants to volunteer let me know, but that won't be happening right away.

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