General documentation

DocInsight
1

Is it possible to add a tag for general documentation not connected to any datatype, function or procedure in the code but still accessable in Documantation Explorer and the exported documentation?

Regards

2

We’re going to introduce Markdown-based help authoring (with some extensions). Is this what you had in mind? (No plan for XML based topics)

We will also consider supporting inline Markdown-based documentation comments in source code alongside XML doc comments. This functionality will be available in both DocInsight and JetPascal, though it isn’t supported by Delphi’s built-in Code Insight.

3

I was hoping for a XML-based topic since I’m not that familiar with the Markdown-based documentation.
One may get around this by dummy-declarations in the code on which I hook the documentation but I’m afraid that it will be confusing for future developers. Do you have any suggestions on how to make a dummy-declaration to be self explained?

Regards

4

I’ve seen a similar approach in the Rust ecosystem. It’s still unclear what these documentation blocks are for and how they’re consumed, but a few ideas come to mind:

  • Place them in dedicated “dummy” units within the same folder if possible
  • Add conditional defines (e.g., a DOC build mode)
  • Use a consistent naming convention

It would be helpful if you could share a few concrete examples—we might find inspiration for new features.

5

Hi, sorry for the late respose.
Try to explain how I sloved general documentation with DocInsight. Perhaps not optional and I am grateful for any input that will improve my model.

First I created a unit called A_SystemDocumentation
Two datatypes is declared:

type
TDocumentation = class(TObject); // Used as “chapters” in the documentation
TSystemdocumentation = boolean; // Used as documentation objects

Then I build the documentation as follows:

DatabaseDocumentation = class(TDokumentation)
private

  Checklists    : TSystemDocumentation;

  TreeStructure : TSystemDocumentation;

  FMEA	    : TSystemDocumentation;

end;

ProgramDocumentation = class(TDokumentation)
private

  RecordCodes              : TSystemDocumentation;

  Createing_Checklists     : TSystemDocumentation;

  Creating_TreeStructure   : TSystemDocumentation;

end;

and so on …
In this structure I can document each variable of TSystemDocumentation and get some kind of structure in the generated HTML-dokumentation from DocInsight.

What I miss so far is the possibility to use records within the documentation strukture in order to create sub-chapters like:

  Creating_TreeStructure : record
    Subject 1 : TSystemDocumentation;
    Subject 2 : TSystemDocumentation;
    Subject 3 : TSystemDocumentation;
  end;

Regards
Dag

6

I think this is only a workaround for simple general documentation. I am trying to introduce experimental Microsoft Learn presentation and possibly lightweight markdown authoring in 6.1. (Html output first, more features in future releases). Then general documentation will get first-class support. Topics and API elements can also be cross-referenced.

Screenshot 2025-08-20 at 15.38.47
Screenshot 2025-08-20 at 15.38.472524×1660 290 KB

7

Hi,
Of course is it an simple workaround for general documentation since DocInsight not is providing a tool for that purpose. You asked me for an example on how I solved it.
Could you please explain what you mean with "Topics and API … "? I can’t follow you there.

Regards
Dag

8

Got it. I saw similar pattern in some rust projects (creating module for documentation purpose).

Markdown is very lightweight and widely used. Code element can be referenced like this in markdown file:

Spring unit has a type named [`Spring.Nullable{T}`].

XML doc comment can link to markdown topics:

/// <see xref="introduction" />

DocInsight generator will create links in documentation output.

Note: Syntax not finalized.

9

Awaiting a solution on general documentation I really should appreciate the possibility to have Records in my documentation structure.
Talking about records, have you considered my previous suggestion on documentation of these in general?

Regards
Dag

10

Yes. I want to support documenting members in anonymous types. However, the generated doc structure and layout might not be exactly same as you expected. what about just embed the documentation in a single field and link to another type when it becomes bigger? I think you don’t need this workaround for a long time.