Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

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

juanccilleruelo started this conversation inGeneral
Discussion options

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.

You must be logged in to vote

Replies: 3 comments 6 replies

Comment options

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

You may use thesupport forum for questions.

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

You must be logged in to vote
1 reply
@juanccilleruelo
Comment options

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 ofhttps://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.

Comment options

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 likeDocumentation Insight (commercial) orPasDoc (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 standardXML 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?

You must be logged in to vote
3 replies
@juanccilleruelo
Comment options

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 thatDephi 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
Comment options

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
Comment options

Anyway, PasDoc seems a better option than Documentation Insight.

Comment options

There are three advantages of usingXMLDoc

  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 aDocument Insight by DevJet orDoc-o-Matic. Or you could usePasDoc.

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

You must be logged in to vote
2 replies
@lmbelo
Comment options

The XMLDoc is a great choice.

@pyscripter
Comment options

Agree. Happy to accept PRs with XMLDoc comments.

Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Category
General
Labels
None yet
4 participants
@juanccilleruelo@jimmckeeth@pyscripter@lmbelo
[8]ページ先頭
©2009-2025 Movatter.jp