Re: [Pasdoc-main] What the best way to specify examples?

[Michalis K. <mic...@gm...>]

2016-09-14 18:21 GMT+02:00 silvioprog <sil...@gm...>:
>
> Hello,
>
> I've used the @code feature adding examples to my documentation, however, I don't know if the best approach, because I have some long examples with many lines (~250 lines).
>
[...]
> So I have a question: can I do something like this with PasDoc? If so, can I put an entire existent example the documentation? For example, supposing I have a real example named "MyExample.dpr" in my examples directory, at the documentation directory, I would do:
>
> TSomeClass = class
> public
>   { This is blahblahblah. @example(../Examples/Cosole/MyExample.dpr) }
>   procedure SomeMethod;
> end;
>
> Thank you!
>

There a couple of questions and features here:)

1. As for the best way to present the longer example code: the
@longCode tag makes a long code example look pretty (with colors, bold
keywords etc.), see http://pasdoc.sipsolutions.net/LongcodeTag . The
result looks like this:
http://michalis.ii.uni.wroc.pl/castle-engine-snapshots/docs/reference/html/CastleImages.html#AddLoadImageListener
.

2. There is no way to include a Pascal source file and make it look
like a @longCode output, unfortunately. It would be a nice feature,
but it's just not done yet. Contributions would be welcome, a tag name
like @includeCode would be consistent with our other tags. It should
be easy to do:)

  What you can do now is to use @include
http://pasdoc.sipsolutions.net/IncludeTag to include a description
from another file. But that another file will have to include
@longCode tag ... So it will not be a correct (compileable) Pascal
code, if that is what you need.

  And you cannot use @tags within @longCode, so you cannot circumvent
this limitation by writing "@longCode(#@include(a.pas)#)".

  Hm, I came up with such hack: You can create a compileable file with
@longCode inside by using comments:

------ (paste this as aaa.pas)
// @longCode(#
begin
  Writeln('aaa');
end.
// #)
------

  And then include it with @include(aaa.pas). So it's close to what
you need... *but* the resulting documentation will have extra "//"
characters.

  I'm afraid we should just implement a tag like @includeCode to make
it really Ok.

3. As for linking to a separate page: this is not possible for now.

  Although we have a support for complete, separate documentation
pages, it is right now used for introduction / conclusion pages:
http://pasdoc.sipsolutions.net/IntroductionAndConclusion . An example
output is inside the PasDoc's own documentation:
http://pasdoc.sourceforge.net/autodoc/html/index.html . The first page
"Pasdoc Sources Overview" is a separate page written using our @tags .

  However, it is not yet possible to create arbitrary separate
documentation pages whenever you want. It's another feature that I
would accept patches for (like an @includePage tag, that can be used
anywhere within a description, to create new page and also link to
it).

Regards,
Michalis