[lazarus] Lazarus Object Documentation

[Michael A. Hess]

Robert Scott Horning wrote:
> 
> I think some very basic items which would be useful to programmers
> should be in the source code itself, such as a brief description of
> each method (in the method header) and a one sentence description of
> each parameter.

Agreed.

> More verbose descriptions should be available in the external files,
> as well as example code snippets and longer explanations for some
> objects (like what is a TStream and when should you use one.  Oh,
> you've never used a TStream? Well here are some good examples... ect.)

There is no reason why it can't be in both places. If I remember PasDoc
will first use the information found in the .pas file in the form of
comments. If it then finds information in the external documentation
file for that item it uses that and ignores the comments in the source
code.

This way some simple information for the coder could be made available
in the source code. The same information plus more complex explainations
could be in the external document.

It would then be possible to make 2 sets of documentation. The first
could be a simplistic handbook that is built using just the comments
found in the source code. It would just inform the knowledgable coder
about those few pieces of information he might need. The second set of
documentation could be more complex and be built with the external
document file which has the complex explainations. This would be for the
novice, beginner or as you put it the person who has never used streams
and needs more of a tutorial.

We would have the best of both.

-- 
==== Programming my first best destiny! ====

Michael A. Hess      Miracle Concepts, Inc.
mhess at miraclec.com   http://www.miraclec.com