Testcase:

{ 
  @longcode(
  {$D+}
    Some long code
  )
}
unit foo;

interface

implementation

end.

https://fountain.io/
https://github.com/nyousefi/Fountain

The generated HTML page displays UTF-8 characters (eg. ü, ä, ö) normally on my local machine, yet when uploaded to GitHub Pages it causes errors.

The head of the html file only contains:
<meta http-equiv="content-type" content="text/html; charset=iso-8859-15">

Hello.

I've used declarations like @link(Sagui.Malloc) to reference functions, however, I would like to declare something like @link(Sagui.Malloc()), but when ending the content by () it generates "UNKNOWN" instead of Sagui.Malloc().

Thank you!

So I ran tests over master branch and got some differences

Path	Filename	Extension	Status	Lines added	Lines removed	Last Modified	Size
tests/testcases_output/html/large_test/AllFunctions.html	AllFunctions.html	.html	Modified	12	12		
tests/testcases_output/html/large_test/AllIdentifiers.html	AllIdentifiers.html	.html	Modified	27	27		
tests/testcases_output/html/ok_nested_types/ok_nested_types.html	ok_nested_types.html	.html	Modified	55	55		
tests/testcases_output/html/warning_back_comment/PASDOC-OUTPUT	PASDOC-OUTPUT		Modified	5	5		
tests/testcases_output/html/warning_back_comment_class/PASDOC-OUTPUT	PASDOC-OUTPUT		Modified	1	1		
tests/testcases_output/htmlhelp/large_test/AllFunctions.html	AllFunctions.html	.html	Modified	12	12		
tests/testcases_output/htmlhelp/large_test/AllIdentifiers.html	AllIdentifiers.html	.html	Modified	27	27		
tests/testcases_output/htmlhelp/large_test/docs.hhk	docs.hhk	.hhk	Modified	31	31		
tests/testcases_output/htmlhelp/ok_nested_types/ok_nested_types.html	ok_nested_types.html	.html	Modified	53	53		
tests/testcases_output/htmlhelp/warning_back_comment/PASDOC-OUTPUT	PASDOC-OUTPUT		Modified	5	5		
tests/testcases_output/htmlhelp/warning_back_comment_class/PASDOC-OUTPUT	PASDOC-OUTPUT		Modified	1	1		
tests/testcases_output/latex/warning_back_comment/PASDOC-OUTPUT	PASDOC-OUTPUT		Modified	5	5		
tests/testcases_output/latex/warning_back_comment_class/PASDOC-OUTPUT	PASDOC-OUTPUT		Modified	1	1		
tests/testcases_output/latex2rtf/warning_back_comment/PASDOC-OUTPUT	PASDOC-OUTPUT		Modified	5	5		
tests/testcases_output/latex2rtf/warning_back_comment_class/PASDOC-OUTPUT	PASDOC-OUTPUT		Modified	1	1		

Are expected results non-actual or I have tests run incorrectly?

Well the title is all I need to say :)

It seems like, there is no support in PasDoc GUI (at least not in the latest release, 0.15.0) for this rather useful feature. Without this, the option is --autoLink (which does have a GUI equivalent) is rather annoying. Common names as member names in records or classes are becoming a real PITA in the documentation.

Hello.

Please consider the following small doc:

    { Specifies the library to be loaded dynamically.

      @raises(EBrookOpNotAllowedLoadedLib if the library is already loaded.)}
    property LibraryName: TFileName read FLibraryName write SetLibraryName;

However, it seems the @raises tag is not parsed 😞 :

I'm using PasDoc GUI + PasDoc 0.15.0 and this configuration.

Hello.

Is there any trick to customize a text color and put it at the end of a block? For example, something like @color(red @bold(Warning:) blah blah blah.) or @color(#ff0000 @bold(Warning:) blah blah blah.) would generates a bold red text after a @returns element. Another way which should work, would:

    { Some description.
      @param(ASomeParam[in] Some param.)
      @returns(@True if bla bla bla.)
      <span style="color:green;"><b>NOTE:</b></span> Some relevant note.
      <span style="color:red;"><b>WARNING:</b></span> Some important warning. }
    function Foo(const ASomeParam: string): Boolean;

that would generate (image produced by GIMP):

Thank you!

I guess there's no sense in having tags inside @code, isn't it? Now this causes unneeded markdown formatting,

`DO_SMTH_BAD`

turns to
'DOSMTHBAD'

See https://stackoverflow.com/a/15841240 for information on how to include a map file so that clicking on a node will bring you to the associated URL. If dot is used to generate the png image, it can also be used to generate a corresponding map file that can be used for this.

Since some of the nodes (units) do have URLs generated for them, and others might not have a URL, it could also be helpful to change the shape or color of the nodes that can be clicked on.

you add internal support for rmarkdown?
https://github.com/rstudio/rmarkdown
https://github.com/rstudio/rmarkdown
this will with #73 not to mention help me in making an actors notebook/ editor app and i want my app to be able read as many file formats as possible with out the user have to think about, ie wysiwyg.

According to recent recommendations of HTML standards

I suggest you, to change

<body>
<div class="container">
<div class="navigation">
<h2>Title</h2><hr>
<ul>
  <li><a href="AllUnits.html">Units</a></li>
  <li><a href="ClassHierarchy.html">Class Hierarchy</a></li>
  <li><a href="AllClasses.html">Classes, Interfaces, Objects and Records</a></li>
  <li><a href="AllTypes.html">Types</a></li>
  <li><a href="AllVariables.html">Variables</a></li>
  <li><a href="AllConstants.html" >Constants</a></li>
  <li><a href="AllFunctions.html">Functions and Procedures</a></li>
  <li><a href="AllIdentifiers.html">Identifiers</a></li>
</ul>
</div>
</div>
<div class="content">
<h1 class="allitems">All Classes, Interfaces, Objects and Records</h1>

<table class="itemstable wide_list">
......
</table>

</div>
<hr><span class="appinfo"><em>Generated by <a  href="https://github.com/pasdoc/pasdoc/wiki">PasDoc 0.15.0</a>. </em>
</span><hr>
</body></html>

and the beginning of css will become, something like that :

body, html, .container {
  margin: 0;
  padding: 0;
}

body {
  font-family: Verdana,Arial;
  color: black;
  background-color: white;
}

.container {
  width: 100%; 
}

.appinfo {
  display : block;
  text-align : center;
}
.navigation {
  width: 100%;
  color: white;
  background-color: #353535;
  margin: 0;
  /* padding-bottom is a little larger, to make navigation column have some
     nice height even when td.content column is very small. */
  padding: 0em 0em 0em 0em; 
}
.navigation li { 
  display :inline-block;
  margin : 0em 0em 0.5em 0em;
  padding: 0em 0em 0em 0.5em;
  border : none;
}
.navigation h2 { 
  margin-top : 0em;
  padding-top : 0.3em;
  text-align: center;

}

.content { padding: 1em; }
.content h1 { margin-top: 0; }

img { border:0px; }

hr {
    border-bottom: medium none;
    border-top: thin solid #888;
}

a:link {color:#C91E0C; text-decoration: none; }
a:visited {color:#7E5C31; text-decoration: none; }
a:hover {text-decoration: underline; }
a:active {text-decoration: underline; }

.navigation a:link { color: white; text-decoration: none; }
.navigation a:visited { color: white; text-decoration: none; }
.navigation a:hover { color: white; font-weight: bold; text-decoration: none; }
.navigation a:active { color: white; text-decoration: none; }

it will be more easy for making custom theme and to be responsive

Best regards

Please support/allow the & prefix.
The & prefix is used when you want to use a reserved word as a name for something.
Pasdoc currently seem to abort parsing f the containing file when this happens.

Documentation here

Example usage of the & prefix:
`
{$AppType Console}
program test;
uses
System.Classes,System.SysUtils;

type
TTest=class
class var
&begin : Integer;
class constructor Create;
class function &end : Integer;
end;

class constructor TTest.Create;
begin
&begin:=100;
end;

class function TTest.&end : Integer;
begin
Result:=TTest.begin;
end;

var
&var : Integer; // dummy showing a global variable with a reserved name.
begin
&var:=15;
WriteLn(Format('Test=%d var=%d',[TTest.end,&var])); // Notice the lack of & for TTest.end.
end.`

Running this dummy will output "Test=100 var=15".

Hi in this sample

uses
  Classes, SysUtils, fileutil, LazUtf8, lazfileutils, DateUtils,
  LCLIntf, LCLType,
  {$IFDEF Windows}
   Windows, GetText
  {$ENDIF}
  {$IFDEF UNIX}
   BaseUnix, Unix, Unixutil, linux
    {$IFDEF X11_SUPPORT}
     ,xlib
    {$ENDIF}
    {$IFDEF LCLCarbon}
     MacOSAll
    {$ENDIF}
  {$ENDIF};  

pasdoc return this

Entering interface section of unit BZSystem
$IFDEF encountered (Windows), condition is 0, level 0
SkipUntilElseOrFound: encountered directive ENDIF
Skipped code, last directive is ENDIF
$IFDEF encountered (UNIX), condition is 0, level 0
SkipUntilElseOrFound: encountered directive IFDEF
SkipUntilElseOrFound: encountered directive ENDIF
SkipUntilElseOrFound: encountered directive IFDEF
SkipUntilElseOrFound: encountered directive ENDIF
SkipUntilElseOrFound: encountered directive ENDIF
Skipped code, last directive is ENDIF
Error EPasDoc: H:...\BZSystem.pas(58): identifier expected but symbol ";" found while parsing unit BZSystem.pas, continuing...

it seem that the nested IFDEF in UNIX part are not handle correctly

Best regards

Hi in this sample for example :

//{$IFDEF UNIX}
// BaseUnix, Unix, Unixutil, linux
// {$IFDEF X11_SUPPORT}
// ,xlib
// {$ENDIF}
// {$IFDEF LCLCarbon}
// MacOSAll
// {$ENDIF}
//{$ENDIF};

//==============================================================================

const
// Langue utilisée par défaut
cDefaultLanguage : String = 'FR';

The output take all comment above the const

{$IFDEF UNIX} BaseUnix, Unix, Unixutil, linux {$IFDEF X11_SUPPORT} ,xlib {$ENDIF} {$IFDEF LCLCarbon} MacOSAll {$ENDIF} {$ENDIF}; ============================================================================== Langue utilisée par défaut

the only solution is to use //< on the first const

Cheers

Now All*.html files are generated even if there's nothing to write there so they contain just "The units do not contain any *" message. I suggest to not generate html's in such cases thus removing useless files and reducing visual noise in generated docs. Moreover, this would significantly reduce the number of files in repo because most of testcases are very short.

Hi.

Does PasDoc contain any marketing icon (PNG or SVG)? (e.g. like this one for cURL and this one for NeoVIM)

I'm interested to contribute a script like this to generate an appimage for PasDoc, making it easier to fix #80, like Linus Torvalds does for his Subsurface application.

In general, appimage (and other tools like flatpak/snap etc.) requires sizes 16x16, 32x32, 48x48, 64x64, 128x128 and 256x256, but many applications (GIMP, NeoVIM, KiCAD, Etcher etc.) uses only the 256x256 size, for example, icons/subsurface-icon.png. (BTW, we have been using all sizes in our applications at the company)

cheers

I would love to be able to add additional custom files to my documentation, not just an introduction and a conclusion.
Is that already possible and I'm just missing something? If not, I would love to see this feature added.

Wow, sorry for multiple feature requesting! 😅

So, I'm trying to add the returns command multiple times in same function, for example:

{
  Allocates a new memory space and zero-initialize it.
  @param ASize[in] Memory size to be allocated.
  @return Pointer of the allocated zero-initialized memory.
  @return @code(NULL) When size is @code(0) or no memory space.
}
function BrookAlloc(ASize: NativeUInt): Pointer;

but it is not supported. However, what do you think about to support the retval command? It would generate something like this:

It is another Doxygen feature that IMHO would be nice to implement in PasDoc since Pascal programming also allows multiple return values in same function:

Thank you!

Hi,
first sorry for*Outbut --> OutPut.
Like i said in issue #12 . I've finally got a respectable result but i've notice some errors :


here like you see the %region% will not be appear

here links (lenght) here are not display in the same way

here same as above and param have return line instead it will be on the same line (more pleasant)

Here in "All functions and procedure" order are not repsected and see the Sqrt function

I have a question it is possible to avoid @abstract and @br tag. ?

Thanks in advance.

Best regards

Hi,

I wanted to test the generation of documentation on my project. Only the result is chaotic.

The problem is that my library is essentially composed of advanced recordings with private, public fields and internal functions.

Apart from (temporarily) passing them to 'class'.

Is there a tip with pasdoc?

Do you take charge of this in the future?

Best regards

Tags without parenthesis are cool but they only could have single-line parameter. I'd like to expand that to multiline.
I see two options:

• Using "line feed" character like \ (like in shell scripts, C and so on)
  • Pros: well-known scheme
  • Cons: one will have to add this char for every line in parameter

@param some \
  long \
  text

• Read until next @
  • Pros: it will look very nice for arguments/returns/raises of a method, no any excess character.
  • Cons: when a multiline tag is followed by plain text, weird single @ would be required.

@param some
  long
  text
@param some
  long
  text #2

@param some
  long
  text@
Plain text goes here

Opinions?

P.S. Instead of single @ a @br tag could be required. So the parser will sure any multiline parameter ends with a tag.

Hi,
I try to compile and build pasdoc under Embacadero Delphi Rio 10.3.
If I do a "compile all" of the project group I get an error saying that the resource file of the gui is missing.

[dcc32 Error] E1026 File not found: 'pasdoc_gui.res

Is this file really missing or do I oversee something?
Regards,
PifPof73

can someone add support odf file?

Hello,
When method parameters have descriptions, in the documentation the first word of the description is next to the parameter name.
Like, for example:

<dl class="parameters">
<dt>AValueChaîne</dt>
<dd>dont la somme MD5 sera calculé.</dd>
</dl>

Here, the parameter name is just AValue.

Hi There . sorry for submit my question as an issue.
Can i get procedure and functions code as their name ?
did you implant this ?
sorry for my bad english
best regards

Hello.

Consider the following code snip:

...
  public
    { Creates an instance of @link(TBrookLibraryLoader). }
    constructor Create(AOwner: TComponent); override;
    procedure DefineProperties(AFiler: TFiler); override;
...

I want to skip the method DefineProperties, generating only the Create's documentation. Is there any way to do that? (I'm using PasDoc GUI [0.15.0], so I don't know what is the full command line passed to the pasdoc tool)

Found some valid cases that scanner/parser cannot handle. They're quite unusual and even rare but let them remain here.

• National identifiers. Still rather a curious feature than a frequently used compiler ability (and thank God for it!) but anyway. Delphi supports them since 2009. Implementing this one will require full set of Unicode stuff which is built-in in modern compilers but ancient versions are losers.
• Parser requires ; after deprecated directive while it's not obligatory
• Scanner breaks on reading ASM block with a char constant enclosed in double quotes (allowed syntax)

asm
        CMP     AL,"'"
        MOV     AL,byte ptr [ESI]
end;

Now @author tag is written so that a link is written as well. I suggest to modify output to write link only in href attribute. Thus, HTML output will show only pretty author name and not a probably long url/email

Hello dudes.

Firstly, thanks for migrating PasDoc to Github hosting, this is one of the most productive platforms for code managment.

So, I'm using Doxygen to generate the documentation of a C library I'm developing, and I found some awesome ideias that maybe useful for PasDoc. For example:

/**
 * Reads a zero-terminated value from string handle @p str.
 * @param[in] str String handle.
 * @param[out] val Value to be read.
 * @param[in,out] len Pointer to specify then store the value length including the terminating null byte (<tt>`\0`</tt>).
 * @retval 0 - Success.
 * @retval -EINVAL - Invalid argument.
 * @retval -ENOBUFS - No buffer space available.
 */
extern int bk_str_read(struct bk_str *str, char *val, size_t *len);

It generates something like this:

Notice the [in], [out] and [in,out] in front of its parameters. It is similar to var and out of Pascal, or something like a parameter reference pointer. So, in PasDoc-style documenting, it would be:

{
  Frees a memory space previous allocated by BrookAlloc().
  @param APtr [in] Pointer of the memory to be freed.
}
procedure BrookFree(APtr: Pointer);

and it would generate something like this:

What do you thing? 😃

Thank you!

Check following code

// configurable globals
var
  // sample var
  Foo: byte;

It makes Foo have description configurable globals sample var. If we try to @exclude the first comment, the variable gets excluded too.

I'm just using the PasDoc HTML export for documentation, but the generated HTML code is not got parameterizable and not responsive for mobile devices.

So I would be nice, if a more modern HTML5 export can be implemented. so the Bootstrap library with the built-in Grid-System can be used for building tables and other design elements. With a definied set of class names for all element tags, a nice HTML layout can be designed

Docs say that longcode allows using without additional markers. Nevertheless, if we try it, it generates weird output:

(*
  @longcode(
    { Some multiline 
      comment }
  )
*)

unit ok_longcode_comment;

interface

implementation

end.

Result:

@(longcode
    { Some multiline 
      comment }
  )

I see this content is constructed in TTagManager.CoreExecute and changed in TDocGenerator.HandleLongCodeTag but I'm not sure why TTagManager.CoreExecute creates such weird value.

Hi.

It would be nice to provide an official Docker image (Alpine-based?) with pasdoc command line tool. Some popular tools adopted this concept, providing executable containers, for example: curl-docker. Also, an official image would provide an easy way to install PasDoc in any Linux distribution, even when PasDoc is not available on a package manager (e.g. Fedora DNF).

Thank you!

I'm trying to use PasDoc to create a documentation of an existing project with> 500,000 lines of code.
My problem is the rule of simple comments within a line of code.

Actually PasDoc use this definition regarding bei the Wiki "WhereToPlaceComments"

TMyClass = class
MyField: Integer; //< Description of MyField
procedure MyProc; //< Description of MyProc
property MyProp: Integer read MyField write MyField;
//< Description of MyProp
end;
If you use a CommentMarker, the "<" character must be placed right after your chosen marker.

My suggestion is to change PasDoc to automatically accept comments at the end of a line of code as comment of the line itself and not as a comment of the following line.

This should be independed of any extra CommentMarker, because I would not check all existing code to place CommentMarker at line-comments.

Simple comments of a line with sourcecode are for the line itself.
Simple comments of a new line are always comments of the following line of code.

I think these rules will be more general for using PasDoc with standard source code.

As compromise I can imagine to add a new command feature to define "--marker-simplecomments=<".
If "--marker-simplecomments=" (empty or not set) then the assignment of the simple comment depends on existing or not existing code at the beginning of line.

Thank you
Regards

Hello buddies.

What do you think about to support Markdown in PasDoc? Markdown is present in many other documenting tools (Github wiki/docs/blogs, Doxygen, JavaDoc, VSdocman etc.).

Thank you!

The graphiz dot-file export creates an error on class names with a dot inside the name:

Delphi source: MyThread = class(classes.tthread)
wrong pasdoc dot-result: DiGraph Classes { MyThread -> classes.tthread }
correct dot-solution: DiGraph Classes { MyThread -> "classes.tthread" }

So if an dot is within the name on the right side, double-quotes must be set

And with that it should be helpful if dot is execute by PasDoc directly and put on HTML export a SVG file as menu item within the documentation

Tag @raises requires exception class as 1st word but it's rather frequent to have general Exception there. So auto-linking tries to search for exception identifier and produces warning. Maybe we should process the very word Exception as standard identifier and not try to auto-link it.

Special tag that would change PasDoc behavior, just like most linters, coverage scanners and similar tools have.
Applications:

• Skip probably large pieces of code (@exclude affects only one item below)

// @pasdoc(skip start)
procedure Foo;
function Bar;
...
// @pasdoc(skip end)

• Enforce options. For example, some units in a project are not PasDoc-ready yet but in order to create full docs we still have to run PasDoc with all the units and, of course, with the same parameter set. Option names could be the same as command line parameters for simplicity, and +/- enables or disables the option.

// @pasdoc(opt +auto-link)
// @pasdoc(opt -markdown)
...

To think: returning a previous option value. Just adding opposite operation isn't correct - the option could have had the same value.
> pasdoc foo.pas

// @pasdoc(opt -markdown)
...
// @pasdoc(opt +markdown) - WRONG!

so probably default value should be saved instead of overriding and special command should return that value, like

// @pasdoc(opt ?markdown) - too C-style...
// @pasdoc(opt def markdown) - more Pascal-ish

could you add syntx highlighters for Fountain and CriticMarkup?
Fountain
https://fountain.io/
https://github.com/nyousefi/Fountain

CriticMarkup
http://criticmarkup.com/
https://github.com/CriticMarkup/CriticMarkup-toolkit/

Hello.

Please take a look at the following doc (notice Windows and Posix.Errno together sounds that something is wrong):

it was generated from:

[snip]

uses
{$IF DEFINED(MSWINDOWS)}
  Windows,
{$ELSEIF DEFINED(FPC) AND DEFINED(UNIX)}
  BaseUnix,
{$ELSEIF DEFINED(POSIX)}
  Posix.Errno,
{$ENDIF}
  SysUtils,
  libbrook,
  Marshalling,
  BrookHandledClasses;

[snip]

however, it depends on IFDEFs:

...
{$IF DEFINED(MSWINDOWS)}
  Windows,
{$ELSEIF DEFINED(FPC) AND DEFINED(UNIX)}
  BaseUnix,
{$ELSEIF DEFINED(POSIX)}
  Posix.Errno,
{$ENDIF}
...

so I would like to remove them (system units) from my documentation.

I'm not sure if/how PasDoc handle situations like that. If we doesn't have such feature, this topic title should be edited to feature request. 😃

As described here.
WIP in branch feat_parse-impl

Checklist:

• Support standalone routines (done incl. any nesting level)
• Support record/class members (done incl. any nesting level)
• Decide what to do with overloads (done for now with index-based solution. In the future this should be solved adding parameter types to names and/or grouping)
• Run current parsing code with lots of real units (done with several testcase fixes, merge mode "join" produces the same output as without new changes)
• Add command line option
• Add docs

(optional)

• Maybe parse internal items as well and add them with a special flag similar to visibility
  Pros: ability to generate "advanced" or "developer" docs
  Cons:
  • lots of work
  • lots of unwanted stuff in output - better to have ability to specify members that shall go to docs, something like a new tag @internal.
• Support back comments to allow description after method header (like in VTV)
• Add tags for making "virtual" descriptions that are not tied to real declaration, to place long descriptions in impl section and keep intf section clean. Something like @describe (TClass long long text). Only necessary for classes/records and their properties.

I'm using PasDoc within a Docker container, so it would be nice, if I can create the PasDoc settings.psd via comandline with a default setting type, so I can modify it with tools like nano or vi on my Docker commandline (the psd file extension match also to Adobe Photoshop, an ini or yaml file could be better)

Hello.

It would be nice to specify external URLs, something like @url(<URL>) or @url(Some description <URL>), e.g: @url(https://www.gnutls.org) or @url(GnuTLS library https://www.gnutls.org).

Possible parsing logic:

• If the content starts with http:// or https://, it is an external URL, so it is generated as simple tag <a href="http://some-url"></a>.
• If the content start with any word or multiple words separated by empty space and is followed by http:// or https:// after the empty space, it is a description followed by an external URL, so it is generated by a full tag <a href="http://some-url">Some description</a>.
• If a content doesn't contains any http:///https://, it is put as it is, i.e., no tag <a>.
• PasDoc doesn't checks or validates any external URL, it just puts it to the generated <a>.

Thank you!

I compiled PasDoc with Delphi 10.3 Rio and (in PasDoc_Items.pas) it refers to TrimRightSet().

AFAIK, there's no built-in TrimRightSet() in Delphi. So it throws an error.
To solve that, add this right above procedure TBaseItem.StoreCVSTag().

{$IFNDEF FPC}
function TrimRightSet(const AText: string; const ACharS: TSysCharSet): string;
var
  Length1: Integer;
begin
  Result := AText;
  Length1 := Length(Result);
  while (Length1 > 0) and (CharInSet(Result[Length1], ACharS)) do begin
    Dec(Length1);
    SetLength(Result, Length1);
  end;
end;
{$ENDIF FPC}

Hello.

It would be nice to add support for something like Doxygen's \note and \warning commands.

Example at bottom of this picture:

There are two issues here. First, fixed length format (the one with the double colon at the beginning and #$ at the end) is not recognized.

Second, in the floating format, while it is recognized, the text literal UTC is wrongly added to the time stamp, which is wrong. SVN documentation clearly states:

"Unlike the Id keyword, which uses UTC, the Date keyword displays dates using the local time zone"