It's time for a new development release.  What's been going on behind the scenes?

I've migrated Natural Docs from the .NET Framework to precompiled .NET 8 binaries.  What does that mean for you?

The biggest benefit is that Apple-silicon Macs and Windows Snapdragon PCs will be faster and more efficient.  They're ARM64 chips, and now we have ARM64 binaries!  My testing showed the "resolving links" stage on an M1 Mac takes 30% less time this way.  The parsing and building stages won't see as big an improvement but that's because they're more I/O-bound.

Up until now I've relied on Mono to run Natural Docs on Macs, but Mono only emits x64 instructions (at least the version on mono-project.com anyway.)  That means it must then also be run through translation layers like Apple's Rosetta.  Having a native ARM64 version allows it to skip all that and run at full speed.  Also, Apple will be discontinuing Rosetta in a couple of years so this had to happen eventually.

So now you can just download and run the new macOS and Linux binaries without installing anything else.  You don't need Mono anymore.  You don't need to install anything for .NET either, all the components it needs are compiled into Natural Docs itself.

But wait, isn't bundling .NET going to bloat Natural Docs?  I was worried about that, not wanting it to turn into a 100MB download or become heavy like Electron apps, but I was pleasantly surprised.  The libraries get stripped down to only the parts you actually use, and Natural Docs has a very light footprint, so the downloads are all less than 5MB in size.

The web site will automatically detect your system and select the correct download for you.  However, only Chrome and Edge allow it to detect the processor type so you may need to double check it if you're using Safari or Firefox.  All downloads are available by clicking "Other Platforms and Options".  I didn't make any 32-bit builds because I assume no one needs them, but you can let me know if I'm wrong.

So I alluded to a potential new feature in the last update, and it's something that's currently only implemented for enums in C#, but it has the potential to expand beyond that.

Suppose you're documenting enum values.  You have to duplicate them in the comment:

/* Enum: Colors
 *
 * Values:
 *    Red   - The color of apples
 *    Green - The color of grass, but also some apples
 *    Blue  - The color of the sky, but not apples
 */
public enum Colors {
   Red,
   Green,
   Blue }

What if you could just document them with a quick comment inline?

/* Enum: Colors
 */
public enum Colors {
   Red,   // The color of apples
   Green, // The color of grass, but also some apples
   Blue } // The color of the sky, but not apples

This is already implemented and working for C# enums.  You can just put a regular comment after any value on the same line and it will be pulled into the documentation.  It doesn't need a keyword or any other kind of header.  You can extend the comment to multiple lines if it needs to be longer, and you can choose to only document some values if the others are self-explanatory.

It doesn't seem like that big a deal above, but when lists get to be a dozen or more values the duplication is more of an issue.  Also, when this idea was first suggested to me it was for documenting simple structs where there would be more space and effort savings.  You could replace this:

/* Struct: Point
 * Represents a point on an X/Y axis.
 */
public struct Point {

   /* Variable: X
    * The horizontal position.
    */
    public int X;

    /* Variable: Y
     * The vertical position.
     */
    public int Y;
    }

with this:

/* Struct: Point
 * Represents a point on an X/Y axis.
 */
public struct Point {
    public int X; // The horizontal position.
    public int Y; // The vertical position.
    }

So C# enums were a proof-of-concept, with other potential applications being simple structs like above, module ports in SystemVerilog, and maybe even function parameters.

However, getting something that works predictably is a bit tricky.  Ideally I'd like both of the struct comment styles above to Just Work™ without needing any special syntax to distinguish between the two approaches.  That might be doable, but the second method is potentially fragile when you try to do it with basic language support.  For example, it wouldn't work once you add a function to the struct, if the parent isn't documented, or if it's longer than a certain length.  If a feature doesn't behave predictably and in ways that are obvious (it doesn't matter if I document the conditions somewhere, people aren't going to memorize them) then it's potentially unreliable, which makes it a bad feature.  It's more robust with full language support but that limits its reach.  So I'm left between "leave it as a niche feature for enums but don't expand it to areas where it can be flaky" and "don't scrap a feature that could be nice in certain conditions just because it wouldn't work in all of them."

There's also the issue of it being triggered unintentionally, but I think I'm going to change it to require Javadoc-style comment symbols (/// or /**) to prevent that.  It's only one extra character and it more clearly says "this is supposed to be documentation."

Another issue is it's not easy to integrate this idea into the rest of the code so it's a bit of a time suck when I could be working on features that are more broadly beneficial, like finally adding more languages to basic language support and adding source links to repositories like GitHub.

I think I'm leaning towards expanding it slowly over time with full language support where it's more robust, but not putting a high priority on it.  Maybe it can be added to basic language support in a few places where I feel it can be reliable.  What are your thoughts?  Would you ever use it for, say, documenting function parameters?

• SystemVerilog was reverted to "basic language support with extra formatting code for modules" because it wasn't meaningfully updated while I was sidetracked with this.  This allows it to remain usable in this release.

• C# will now pull enum values into your documentation whether you write comments for them or not.  So you can document them the old way, use the new quick method above, or do neither and you'll still have all values in your output.

• C# can now handle raw strings like $"""abc""", including multiline and interpolated ones.  It will also now syntax highlight code sections in interpolated strings like $"abc { x + 12 } def".

• PowerShell variables now get prototypes.

• PowerShell syntax highlighting is improved.  This includes highlighting attributes like [string], but it still needs some work when used with function parameters.

• Shebang Scripts now include .sh and .command files by default.

• Console output has been improved so if you're running Natural Docs in a terminal or console window it will show progress as a live-updating percentage.  If it's being captured by an IDE or otherwise redirected it will behave closer to how it did before.

• Exit codes will now be returned so scripts and automated build processes can more easily tell whether a run succeeded or failed.  After running Natural Docs you can check %ErrorLevel% in batch files, $LastExitCode in PowerShell, or $? in bash scripts to see if there was a problem.  As is the convention, a value of 0 means it succeeded and anything else means it failed.

• Other smaller fixes and improvements.