Txt2FPDoc 0.8.4 released

[yamer]

Txt2FPDoc is a command line tool that converts a documentation file written in human readable language to an XML file suitable for FPDoc.

Txt2FPDoc tries to make the documentation file easy to read (almost as readable as plain English) and easy to write (no cryptic tags, only light markups like **bold** and //italic//).

The documentation can be stored in one or more text files or directly included in the source code.

http://yann.merignac.free.fr/txt2fpdoc.html

[wp]

Seems like this is what I've been looking for.

I am pasting here a few lines out of a fpspreadsheet source file. Would these codes be detected correctly by Txt2FPDoc?

Code: [Select]

type
  { Forward declarations }
  TsWorksheet = class;
  TsWorkbook = class;
  TsBasicSpreadReader = class;
  TsBasicSpreadWriter = class;

  {@@ The record TRow contains information about a spreadsheet row:
    @param Row   The index of the row (beginning with 0)
    @param Height  The height of the row (expressed as lines count of the default font)
   Only rows with heights that cannot be derived from the font height have a
   row record. }
  TRow = record
    Row: Cardinal;
    Height: Single;  // in "lines"
  end;

[yamer]

I am pasting here a few lines out of a fpspreadsheet source file. Would these codes be detected correctly by Txt2FPDoc?

No, some change are needed. The following should work.

Code: [Select]

type
  { Forward declarations }
  TsWorksheet = class;
  TsWorkbook = class;
  TsBasicSpreadReader = class;
  TsBasicSpreadWriter = class;

  {** Type: TRow -- TRow contains information about a spreadsheet row.

        Only rows with heights that cannot be derived from the font height have a
       row record.

        Members:
          - Row --  The index of the row (beginning with 0)
          - Height --  The height of the row (expressed as lines count of the default font)
  }
  TRow = record
    Row: Cardinal;
    Height: Single;  // in "lines"
  end;

[wp]

A lot of work for me... But I must confess that your syntax is less obstructive to the source file. Are you thinking of extending the syntax to something like that of doc-o-matic used by me?

[yamer]

A lot of work for me... But I must confess that your syntax is less obstructive to the source file. Are you thinking of extending the syntax to something like that of doc-o-matic used by me?

My main objective for this tool is a simple and readable syntax so I do not intend to make it more complex.

And I specify that this syntax is not mine, it is heavily inspired by NaturalDocs.

[Leledumbo]

I see pasdoc soul here... still a good feature if you like fpdoc output but want pasdoc style documentation.

[yamer]

A lot of work for me... But I must confess that your syntax is less obstructive to the source file. Are you thinking of extending the syntax to something like that of doc-o-matic used by me?

Add the doc-o-matic syntax is impossible without a huge job. With its syntax, Doc-o-matic need to parse the source code. Txt2FPDoc does not parse the source code, it leaves this part of job to FPDoc.

As said Leledumbo, Pasdoc is closer to Doc-o-matic and could be an alternative.

[wp]

What I do not like with pasDoc is that it forces me to add the comments to the interface part of a unit. But I want the interface declarations to be as compact as possible and therefore I put the doc comments into the implementation section. That's what doc-o-matic allows me to do, but pasdoc not. On the other hand, I want to go away from doc-o-matic because it is a commercial product, they do offer a version which is free for non-commercial software but, of course, does not give me enough freedom with formatting etc.

[yamer]

With Txt2FPDoc you can put documentation where you want : interface part, implementation part or external files. Moving to Txt2FPDoc will take some work, but not necessarily more than moving to Pasdoc and less than moving directly FPDOc. If needed, migration from Txt2FPDoc to FPDoc is trivial. And Txt2FPDoc syntax is simple, readable and easy to remember. Of course, I'm probably not fully objective. 

[wp]

Yes, these are clear advantages. To me there is only one disadvantage: the declarations in the source file have to be duplicated for the documentation - I fear docs will never be up to date this way (at least in my case...)

[yamer]

To me there is only one disadvantage: the declarations in the source file have to be duplicated for the documentation - I fear docs will never be up to date this way (at least in my case...)

You don't need to repeat the whole declaration. You only repeat identifiers. And the same applies to FPDoc. Problems only occur if you rename an identifier.

[rvk]

Yes, these are clear advantages. To me there is only one disadvantage: the declarations in the source file have to be duplicated for the documentation - I fear docs will never be up to date this way (at least in my case...)

How do you mean?

The documentation can be stored in one or more text files or directly included in the source code.

So changing your headers above the function "somewhat" and Txt2FPDoc can generate xml files to be used by FPDoc. The generation of these files can be done with a script.

(or are you afraid you won't run that script often?)

[wp]

How do you mean?

Look at this example from above:

Code: [Select]

type

  {** Type: TRow -- TRow contains information about a spreadsheet row.

        Only rows with heights that cannot be derived from the font height have a
       row record.

        Members:
          - Row --  The index of the row (beginning with 0)
          - Height --  The height of the row (expressed as lines count of the default font)
  }
  TRow = record
    Row: Cardinal;
    Height: Single;  // in "lines"
  end; If, for some reason, I rename the member "Row" of the record to "RowIndex", then I have to update the documentation a few lines above, otherwise it would still refer to "Row.

But probably I do not understanding this doc-building process at all...

[rvk]

How do you mean?

Look at this example from above:
//....
If, for some reason, I rename the member "Row" of the record to "RowIndex", then I have to update the documentation a few lines above, otherwise it would still refer to "Row.

Yes... but with your current code:

Code: [Select]

  {@@ The record TRow contains information about a spreadsheet row:
    @param Row   The index of the row (beginning with 0)
    @param Height  The height of the row (expressed as lines count of the default font)
   Only rows with heights that cannot be derived from the font height have a
   row record. }
  TRow = record
    Row: Cardinal;
    Height: Single;  // in "lines"
  end;
you'll have to do that too.

(or am I missing something ?)

(b.t.w. where did you get the marcov-quote  )

[wp]

Yes... but with your current code:..you'll have to do that too.

Oh - not my best day today, sorry... I was thinking of function declarations which are copied by doc-o-matic from the source file into the documentation.

b.t.w. where did you get the marcov-quote

It was there when I wrote the response. He's an admin, maybe he deleted it?