Is there any documentation or classic help file about the components of P4D?

[juanccilleruelo]

It is essential to have this because some doubts are difficult to understand only through the name of the method or property. Or reading and deepening inside the source code.

For example, what's the difference between EvalStrings and ExecStrings methods?

And for single questions like the previous one, it is excessive to investigate through many demos or a mountain of tutorials. We often need short and direct responses, like the ones we found in a help file or a manual.

[pyscripter]

The short answer is no. You are welcome to contribute one.

You may use the support forum for questions.

And incidentally the Eval... methods return a result, the Exec... don't.

[juanccilleruelo]

Ok. I want to contribute.
What is the next step?
Someone needs to decide the tool to use, or can I select it?
Need I to become a collaborator?
Maybe I can begin creating a branch of the project for future integration.

I'm thinking of https://www.helpndoc.com/
It generates eight different output formats. And have a free version for personal use with the next license:
The only restriction is that the Personal Edition of HelpNDoc or its generated files can’t be used for profit: only personal non-lucrative work and evaluation purposes are permitted by the license.
And the next restrictions:
A discreet banner is added in the generated documentation to remind that it has been created by the Personal Edition of HelpNDoc, and some features are not available.

I think that in this case, there is not any problem.

[pyscripter]

The standard way of contributing is to:

• fork the repo
• make changes to your fork
• submit a Pull Request (PR)

The standard way of generating component help is:

• Document the source code using some mark up
• Use a tool like Documentation Insight (commercial) or PasDoc (open source) to generate help output in the desired format (e.g. CHM, HTML, PDF)

We need to decide on the tool which will determine the source code comment format. Once we do that then you can start documenting the source code, Documentation Insight supports the Delphi standard XML Documentation comments. PasDoc supports this format but also supports its own more terse format.

My initial thought is to use the Delphi supported XML comments and PasDoc for output generation since it is open source and free.

@lmbelo @jimmckeeth Any thoughts?

[juanccilleruelo]

In my opinion, these types of documentation with XML and comments inside the code have some significant disadvantages:

It obfuscates the code.

• Because it adds more text than actual code.
• Because it complicates the maintenance of the code.
• Complicates the merges of branches.

The design of the result format, like HTML, PDF, or CHM, does not depend on your intention as a document writer; instead is the result of a third-party decision out of your control.

This must not be paranoic about the Open Source and Free obsession. Think that Dephi is not OpenSource nor Free.

Integrating the help in the Delphi IDE is better to allow the final user to press F1 in the Type or Method written in the code and get the help in a standard form.

This is the method of Delphi. They don't obfuscate the source code with "help content."

See this starting point: Steema Help

[juanccilleruelo]

Another disadvantage of including documentation inside the source code is that it is complicated to add authentic comments.

You'll be ever writing comments with caution of not adding absurd items to the documentation.

[juanccilleruelo]

Anyway, PasDoc seems a better option than Documentation Insight.

[jimmckeeth]

There are three advantages of using XMLDoc

1. Your documentation lives in the code, so when you change the code, you see the documentation and are more likely to update it. This is great for a living project that continues to change and evolve.
2. XMLDoc also powers Help Insight, giving you IDE integration as you code.
3. You extract the comments from the code to create F1 or web-based documentation

I could try and help get a Document Insight by DevJet or Doc-o-Matic. Or you could use PasDoc.

It really comes down to the preferences of who wants to write the documentation...

[lmbelo]

The XMLDoc is a great choice.

[pyscripter]

Agree. Happy to accept PRs with XMLDoc comments.