the property has a stupid typo in the end: ALLL instead of ALL
since the bottom of the page says “generated by PasDoc” it seemed to be a waster to locate and generate a derived adoc file. Would be overwritten anyway.
So i went into D:\DelphiProjects\Libs\Games\castle-engine\src\transform\castlecameras.pas
Indeed, the ALLL typo is there, but then there is another problem. One more chance to score points at trivial patch. yahoo!
Indeed, the WWW page clearly fails to document .Height property. I even was going to add there a short stub like { This property is documented in the @link(Width) chapter } but…
Those @groupXXX commands. The PasDoc’s web site does not list @groupXXX among supported tags. Yets CGE sources suggest it should, and that introducing the stub decription like above would then probably break the logic.
The @groupBegin / @groupEnd are indeed not yet implemented in PasDoc, even though we’d like to have them implemented one day. As a dev in PasDoc, I planned to implement them – that plan is outlined on PasDoc | Documentation tool for Pascal source code . But admittedly I still didn’t implement them, it’s a TODO for a number of years now, and CGE API docs suffer because of it.
This is a good point, I should finally either
implement them in PasDoc, at least in minimal version useful for CGE
or admit they’ll not be implemented soon, as stop using them in CGE.
my gut feelings says you have to say “In every case” or “In all the cases” but not the current article-less “In all cases”, and i personally prefer the former every+singulat phrase. Your bet?
In all the cases, the resulting size is also multiplied by @link(Scale),
by default 1.0.
You can read @link(EffectiveWidth) and @link(EffectiveHeight)
to know the actual projection width and height, calculated using
the above algorithm.
I have some issues with PasDoc syntax (as you probably do with FpDoc)
It seems it tends to consider ANY comment as documentation (compare it with recent Delphi’s DocInsight which (follows JavaDoc?) only considering unsual triple-slash started comments as documentation source).
the idea behind {@groupXXX} seems flaky to my. Consider code re-arrangement due to refactoring, copy-pasting and moving large chunks around… it can become an entangled spaghetti…
Those “mechanically” unrelated comments constitute a linked structure, easily to be broken or entengled with other similar groups.
Frankly, i’d prefer some other but self-contained approach.
there to be some designation of a comment as PasDoc-s target, and then this label would nclude list of Pascal terms/identifiers the article relates too.
In this case it would be like
{ @PasDoc(Width, Height)
Orthographic projection width and height.
maybe even with some optional scope narrowers, like @PasDoc(property:Width) or @PasDoc(TCastleOrthographic.Width) to resolve ambiguities, if any.
Such linking would provide to moving doc-comments away from immediate declaration point, for good or for bad; just like Pascal’s units are broken into interface/implementations, like classic pascal has var-blocks before code blocks not inside, etc.
wikipedia’s like redirects: push from term to doc
{ Orthographic projection width and height.
....
}
property Width: Single read FWidth write SetWidth {$ifdef FPC}default 0{$endif};
{@doc-link(Width)}
property Height: Single read FHeight write SetHeight {$ifdef FPC}default 0{$endif};
the opposite, pull from doc to item. Essentially same as #1 but without mandatory pasdoc-tagging every doc-comment
{ @also-doc(Height)} // .Width is IMPLICITLY linked here as it is now
Orthographic projection width and height.
....
}
property Width: Single read FWidth write SetWidth {$ifdef FPC}default 0{$endif};
property Height: Single read FHeight write SetHeight {$ifdef FPC}default 0{$endif};
PasDoc was actually quite closely inspired by JavaDoc. Doxygen, OcamlDoc are other similar documentation generators that we looked at when developing it.
In CGE I just chose to not use markers, and consider all interface comments as possible documentation. Yes, it adds some burden sometimes. You need to be aware that PasDoc will happily consume your comment and (but this is really seldom in my experience) prevent PasDoc from using some unwanted comment (like a copyright clause at the beginning of include, when your include has 1st identifier that you rather want to leave undocumented for now) from using it. On the other hand, the interface comments are free from markers, and this looks cleaner – and it encourages to make almost every comment in the interface to be part of API documentation.
There’s no perfect solution, and from my opinion the current approach (no markers) works for CGE. . But you can use PasDoc with (required) markers for your projects if you need to.
That’s a baseless speculation, IMO. Keeping the @groupBegin/End together is simply zero problem, in all of our big refactors in CGE this was never an issue.
And one is not forced to use @groupBegin/End for grouping. @groupWith is also an option. See the “grouping” feature thoughts on the page I linked, Michalis Kamburelis | PasDoc . This is a bit like AD 2 that you mention.
