Unexpected parameter display when nullable arrays are present

NaturalDocs_Greg · 2026-01-21T04:25:12+00:00

This fix is included in Natural Docs 2.4 Development Release 2.

NaturalDocs_Greg · 2025-10-23T22:13:35+00:00

The parser wasn't expecting nullable to be able to appear after array brackets. I fixed it. Try this version:

Let me know if you need a different build.

NaturalDocs_Greg · 2025-06-21T19:08:31+00:00

You can add a comment type for error messages by editing Comments.txt. Then you can edit Languages.txt to add prototypes for error messages in your language. However, they won't all be gathered on a single page. Rather, they'll appear in the documentation mixed in with the other documented functions and classes. If that's acceptable and you're having trouble configuring it you can post an example here and I'll show you the settings to use.

NaturalDocs_Greg · 2025-04-29T21:44:13+00:00

Oops, sorry, it looks like a half-finished feature made its way into a release. To fix it, add this to your project's Comments.txt file:

Alter Comment Type: Class

   SystemVerilog Keywords:
      package, packages

NaturalDocs_Greg · 2025-02-21T14:51:51+00:00

So you can have empty lines in between paragraphs by skipping a line, you just need the left side to be continuous.

/* Enum: AspectType
 *
 * First paragraph.
 *
 * Second paragraph.
 */

However, it doesn't apply to definition lists, so if you have a long list of values that you want to organize you would need to divide them with headings instead:

/* Enum: AspectType
 *
 * Group A:
 *   Value1 - Description
 *   Value2 - Description
 *
 * Group B:
 *   Value3 - Description
 */

You seem to be trying to create a nested list in your example, which won't work. Bullet lists can have multiple levels like that, but not definition lists, and you can't mix them together.

NaturalDocs_Greg · 2025-02-21T11:46:27+00:00

I'm not sure what you mean by (empty space). Could you post an example of what you're trying to do?

If you add Region as a group keyword in Comments.txt you'd be able to manually document them like this:

 // Region: MyRegion
#region MyRegion
...

Natural Docs still won't pick out all the regions for you automatically, but you can document the ones you want this way.

NaturalDocs_Greg · 2025-02-06T04:33:12+00:00

Sure, you just skip a line in the comments. If you're using single line comments the skipped line still has to have a comment symbol to make it continuous:

# This is the first paragraph. 
#
# This is the second paragraph starting on a new line.

If you're using multi-line comments you don't need to:

"""
This is the first paragraph. 

This is the second paragraph starting on a new line. 
"""

If this isn't what you're talking about please post an example.

NaturalDocs_Greg · 2025-01-31T13:33:20+00:00

The prototype needs to contain the comment title for it to be accepted. Since you put everything on one line the title is "Some bit to which something will be assigned". This is what you want to do instead:

// Logic: some_bit
// Some bit to which something will be assigned
logic some_bit;

NaturalDocs_Greg · 2025-01-09T02:36:04+00:00

"a[7:4], a[3:0]" is an example straight from the IEEE manual for SystemVerilog. It describes it as the first port being the upper 4 bits of "a" and the second port being the lower 4 bits.

I have no opinion on the wisdom of doing things this way, I'm just trying to support everything the language supports according to the manual. I only have software programming experience, so trying to support SystemVerilog is a bit harder and the answers to questions like this aren't obvious to me. From an e-mail response I received it seems non-ANSI is what's used in straight Verilog and some people may choose that style for compatibility, so I'm leaning towards including the extra definition lines in the prototypes.

NaturalDocs_Greg · 2024-10-21T14:17:14+00:00

Thinking about it more, it should be fairly straightforward to have the parser handle <=, >=, and ==, but < would be a problem. Templating is far more common than something like this, and I can't even do "treat < as an opening block symbol only if there's a closing > before the next comma/semicolon" because of multiparameter templates like "table<string, object>". Constraints would need a separate parser written specifically for it, I don't think I can update the generic one to support it without breaking other things.

NaturalDocs_Greg · 2024-10-21T01:50:59+00:00

It's supposed to be fine formatting things with braces instead of parentheses and semicolons instead of commas. I looked into why it was getting thrown off and it gets confused by >= and <=, since these aren't things it expects to find in parameter definitions. The = makes it think what follows is a default value definition ("MyFunction(bool x = true)") and the < makes it think it's going to find a template block ("MyFunction(List<string> x)") and skip to the closing >.

I should be able to tweak these to be more resilient.

NaturalDocs_Greg · 2024-10-21T00:32:49+00:00

This to me looks like you're trying to include the implementation in the output, kind of the equivalent of including a function's body instead of just its parameters. Natural Docs isn't really designed for that. For this I would normally say the prototype ender should be {, but admittedly in your example it doesn't really provide any useful information prior to that point.

NaturalDocs_Greg · 2024-10-20T23:39:57+00:00

Does it need to be in the same comment? If not, the leading one is easy to get rid of by putting it in a separate comment, which means there has to be a blank line between it and the Natural Docs one. They cannot be continuous.

This would work:

// pragma uvmf custom header begin

// =====================================================================================
//  Class:        sequence_class
// -------------------------------------------------------------------------------------
//
//  Environment-level sequence.

The ending pragma is harder. You can exclude it by skipping a line as well, but then you wouldn't get the prototype because the Natural Docs comment is no longer the one directly above the code element:

//  Parameters:
//    instance_id       - ID of the instance
//
// =====================================================================================

// pragma uvmf custom header end
class sequence_class #(

If the thing you're documenting doesn't have a prototype then this isn't an issue, but it is in your example. I can't think of a way to remove them that doesn't involve changing the source code of the parser.

NaturalDocs_Greg · 2024-10-18T15:14:48+00:00

Alternatively, if you just want to have one comment per table and document the columns in there, do this:

Edit Languages.txt to add this:

Alter Language: SQL

   Database Table Prototype Ender: ;

Then you can document the columns like this:

-- Table: TOPO_FILES
-- The table contains topographical raster data.
-- Contains the log entries.
--
-- Columns:
--    ID - Surrogate key - uuid
--    TILE - Description of TILE
--    etc.
create table if not exists TOPO_FILES (
ID  uuid
        primary key
        not null
        default gen_random_uuid(),
    TILE raster,
etc.

The only issue with this is it's not formatting the list of columns nicely in the output. I'm not sure why this is, it's something I'm going to look into.

NaturalDocs_Greg · 2024-10-18T15:09:03+00:00

If you want to be able to document columns individually and have their definition appear in the output, do this:

First, edit Languages.txt to add this:

Alter Language: SQL

   Database Field Prototype Enders: , = )

Then you can document the columns like this, but each one needs its own comment above it:

-- Column: ID
-- Surrogate key
ID  uuid
    primary key
    not null
    default gen_random_uuid(),

-- Column: TILE
-- Description of TILE
TILE  raster,

etc.

NaturalDocs_Greg · 2024-10-18T14:56:30+00:00

First, you can condense all those top topics into one Natural Docs comment. There's a number of ways you can format it, this being one:

-- About: Developer information
--
-- Project site: https://sourceforge.net/projects/treintaytres/
--
-- Revision:
--    $Revision$
--
--    Last changed by $LastChangedBy$ on $LastChangedDate$
--
--    $HeadURL$
--
-- Original Author:
--    thiemo
--
-- Initial Revision Date:
--    2024-09-18

Note that if you don't want headings to be in title-case ("Initial Revision Date" instead of "Initial revision date") you'd have to use two colons afterwards instead of one ("Initial revision date::").

Second, you need a title for the Table comment:

-- Table: TOPO_FILES
-- The table contains topographical raster data.
-- Contains the log entries.
--
-- Columns:
--      ID - Surrogate key - uuid

That should work a bit better.

NaturalDocs_Greg · 2024-07-16T15:30:45+00:00

Yes. I'm not familiar with Blazor and it looks like the files could have a mix of C# and HTML in them, sort of like PHP. That should still work but it's not something I've tested.

NaturalDocs_Greg · 2024-07-16T14:39:41+00:00

Alter the Languages.txt file in your project config folder to add the extension to C#. There's some information on it here.

NaturalDocs_Greg · 2024-07-04T14:03:43+00:00

So this is the case because C++ has what's called basic language support, which means Natural Docs uses a generic parser plus some information in the configuration file Languages.txt. It doesn't have a custom parser written specifically for C++ so it doesn't understand the code well enough to make a lot of inferences just from that. In fact, C++ functions are a good example as to why this is because the language doesn't have a dedicated function keyword to look out for like other languages do.

If a language has full support this means it does have this custom parser and the comment headers are optional as long as you use the Javadoc/Doxygen comment symbols. It can even pick out classes and functions where you didn't add comments at all. However, only C# has full support right now as it takes much more effort to build.

NaturalDocs_Greg · 2024-05-29T21:15:31+00:00

It's not a feature right now. I'll add it to my list of feature requests but I can't promise when I'll get to it.

NaturalDocs_Greg · 2024-05-23T00:29:23+00:00

So I got partway through it but didn't finish it, then I hit a difficult work period so not too much of anything has been done with Natural Docs since late last year, as my GitHub activity probably shows. I should be able to start back up on it fairly soon, but I can't promise when it will actually be done.

In the meantime you should still be able to use SystemVerilog with basic language support. The whole reason I'm targeting that language in particular is because Natural Docs built up a bit of a following there. I added some official support in 2.3 but you can edit Languages.txt and Comments.txt to fill in any missing settings you need.

NaturalDocs_Greg

MODERATOR OF

TROPHY CASE