World API documentation fix

1

I was reading the API documentation and I’ve found TCastleBehavior.World is wrong. It says it’s not used in the end but I tested (for curiosity) and it works. Maybe it’s using the wrong comment to extract the explanation.

Also he description of TCastleTransform.World isn’t clear. The way it explains the thing is like it is just another transform. I know it says it’s the “root transform” but it took me ages to realize it refers to the RootGroup>MainViewport>Items thing and not to an item that doesn’t have a parent.

I know you’re using pasdoc to parse the sources and retrieve the documentation from comments. Since this is quite a large project, I recommend to use the -R option and the @include tag to use external files. I use it in Allegro.pas and it works perfect. I know it would be a lot of work to change everything right now but you can start small (create the basic structure) and add it when modifying something.

2

Fixed, thank you! It was using the wrong comment indeed.

See this commit and new version of docs TCastleBehavior.World.

Indeed - good point, thank you, I improved the docs.

See the same commit and new version of docs TCastleTransform.World.

I have a TODO reconcile some naming in CGE, right now we have

  • World
  • Items (at TCastleViewport.Items)
  • “Root transformation”

… and all these terms really mean the same thing. I absolutely agree it (seems) needlessly confusing. I plan to rename things (preserving backward compatibility) to make it all consistent, so likely we will have TCastleViewport.RootTransform, TCastleBehavior.RootTransform, TCastleTransform.RootTransform… should make it more obvious.

I deliberately prefer to put comments in the source code, in the interface section of the unit. I know it makes the interface longer – but I think it also makes it more useful to the reader. A practical advantage of keeping the “code and docs” together is also that it clearly encourages any modifications to the code to be synchronized with docs (e.g. PRs naturally touch the code and docs, when it makes sense, because “code and docs” are so close to each other → every contributor “gets it”).

I realize it’s a matter of taste, I wrote more lengthy thoughts about it on Michalis Kamburelis | PasDoc , section " Should documentation be placed inside units interface, or in separate files ?". PasDoc does offer both ways (one can use @include or –description as you mention).

P.S. I’m also the current maintainer of PasDoc. If you miss anything from it, let me know!

3

Wow, that was fast.

As for external files, I understand. Maybe you can keep the brief description in the interface section and use external files for details, examples and @param, @return and @seealso stuff. Just an idea.

Anyway the documentation is quite good. :slight_smile:

1 Like
4

I’ve found another miss in the documentation:

CastleApplicationMode should be mentioned in Custom Components. I created and registered a behaviour that defines the AI of my enemies and I found them wandering around the map in the editor. The worst part is that when saving the design it saves the new positions, not the original ones! I’ve found the way to turn it off (if CastleApplicationMode <> appRunning then Exit) but for a moment I was lost.

5

Another good point, thank you!

Added section " 11. Use CastleApplicationMode to determine in which context (application running, editor, simulation) the logic works" to Custom Components | Manual | Castle Game Engine docs.

I mention there CastleApplicationMode, why and how to use it, the appSimulation option, and how existing TCastleMoveAttack is using it.

1 Like