Natural Docs 2.1
Embedded Images
Image support was the biggest thing missing from 2.0 that was in 1.5. If you don't recall 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 or on the command line with -img. It will search all these locations when looking for the image.
Better Support for SQL
Natural Docs can now parse and format complex SQL prototypes like this:
I designed it to handle Oracle's PL/SQL and Microsoft's Transact-SQL. Let me know if there are additional SQL variants that it doesn't handle well.
Better Support for Java
Natural Docs can now handle Java's @annotations and format ones with parameters:
This is good for things like JAX-RS that use it a lot:
Better Support for SystemVerilog
I 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 soon. Since I'm not familiar with the language I can use some SV users to bounce questions off of, so if anyone wants to volunteer let me know.
Better Support for Other Languages
-
Python: Added support for function @decorators and improved syntax highlighting all around.
-
Lua: Basic support is now included out of the box. It has special code to support its --[==[ comment format. It also permits using ]]-- as a closing comment symbol even though that's technically a closing comment followed by a line comment. Some people like it for symmetry.
-
C/C++: Structs get prototypes now.
-
PHP: Improved documenting parameters. Optional types wouldn't be pulled from the prototype into the parameters list correctly before.
Smaller Things
-
Improved code fonts for macOS and Linux. You're not stuck with Courier now.
-
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".
-
Smarter rebuilding. Changing Languages.txt or Comments.txt causes all the source files to be reparsed but it won't rebuild all the output, only the things affected by the changes. Running Natural Docs with --rebuild-output will now rebuild without also reparsing unchanged source files.
-
Performance improvements. Shaved 10% off the parsing and link resolving stages.
-
Fixed merging issues when there are three or more source files for a single class.
-
Fixed some crashes. Also included 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.
-
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.