[fpc-devel] [RFC] fpdoc output comment from the source

[Michael Van Canneyt]

On Sat, 3 Dec 2005, L505 wrote:

>
>
> > Florian Klaempfl schrieb:
> > >
> > > Why ;)? Indeed, if you want generated docs from comments, better use pasdoc.
> >
> > the source scanner used by fpDoc supports reading of comments for quite
> > some time; but as I already told you (or was it Mattias?), the final
> > support in fpDoc is still missing.
> > If there is really interest in this feature, I will have a look at it.
> > (And no, I didn't inspect the sent patch yet.)
> > Any more opinions? Important, not so important?
> >
>
>
> I think comments will be useful and important for developer versions of the
> documentation. Users may not care about the comments in the source code, but it will
> be really useful for a "developer version" of the docs. Many times I write comments
> in the code describing what the code does, so this comment feature in FPDOC would
> help us make developer documentation clearer (users reading the docs, may not care
> about comments so much).
>
> Kind of unrelated, but I'll be working on a CGI program that taps on top of the FPDOC
> generated HTML files and allows users to make notes and comments via their web
> browser underneath the help documents. The way to get users do more work in writing
> documentation, is to have a comment system right up live on the website. Even the PHP
> manual does this ;-)

Please make sure that the fpdoc commenting logic is clearly separated from
the CGI logic. This way your changes can maybe be incorporates in the FPC
sources and website.

The end goal is a CGI system which creates HTML on the fly straight from
sources and XML documentation.

>
> Even though I'm not a fan of XML in many situations, I find FPDOC is a really useful
> and an awesome tool - this time XML fits the job well since the tags are sparse (lots
> of data between the tags).

We also like to think so ;-)

Michael.