My 2 cents.

I would like to see us continue with PasDoc if at all possible. Currently we are one of the major users of PasDoc. So that being the case if we need a feature it is an easy matter to ask the developer and he adds it. Currently it provides HTML and LaTex output. It would be great if we could get XML output. Then we could manipulate and combine that into a real manual at some later date.

Currently the output from PasDoc seems limited due to the fact that virtually on comments are available in the code. More comments better documentation. I think the best way to attack it is to use the external file for the comments. I find that excessive comments in the source code makes the code harding to read and edit. Placing the comments in an external file will let you be as verbose as you wish since it will only be used by the documentation tool. If we generate the documentation from the source code then we know that the documentation is as close to the current code base as possible. If it is done as a totally separate effort then it can become stagnate and get further and further behind the actual coding effort. However if comments aren't add the same thing will occur.

I would also like to automatically generate the documentation on an almost daily bases. I have not implemented it yet due to the fact that there are next to no comments available making the documentation very limited in usefulness. If we start get some more comments and examples included in the comments file then I can automate the documentation build and it will be on the web site daily with the latest information.

I have looked at PasDoc (it doesnt compile/work when compiled with Delphi...)

some comments:

there are several 'pseudo standards' PasDoc JavaDoc Time2Help ... there are few related things like literative porgramming (Knuths' WEB...) now we have tools like XML and XSL (XSLT processing)

it would be nice to 'integrate' the best of above mentioned into a source/doc
handling structure that would generate docs for multiply formats,

we need some kind of specs on 'general doc comments' for FPK (pascal general)
scanner tools that extract that info and produce XML (to specs we make) XSL template that will transform the XML fied source into ready made HTML or some ASCII format (RTF for winhelp compiler) TeX some tagged format whatever

post processing may be done with TeX or some help compiler tool to get HL CHM files
if the output is CSS enhanced HTML there is no post processig required.

now O know not all can follow me here, but believe me I know what I am talking, when
creating the source/doc/help system as outlined above using freely available technologies
and source code the amount of 'original source code' to be written is absolutly minimal
I can make a bet that its about 10 KB of pure code. (restrictions apply, and not counting
templates as code)

I have made some experiments on this approuch and I can assure it is all doable

Comments?

[ snip

I for one love Borland's help and would like it if someone started a

documentation efffort. We have spoken about using PASDOC. I'm not sure if this is the best choice or not. I would be interested in getting something that was as useful and looked as nice as Borland's.

I would be happy to pitch in. What I think we would need is some

templates that would help others create the pages correctly. Maybe generate some and we can see where we go from there.

[snip]
]

-------------- next part --------------
A non-text attachment was scrubbed...
Name: bin00002.bin
Type: application/octet-stream
Size: 2734 bytes
Desc: "smime.p7s"
Url : http://localhost/pipermail/lazarus/attachments/20000519/5e810842/bin00002.bin

I for one love Borland's help and would like it if someone started a documentation efffort. We have spoken about using PASDOC. I'm not sure if this is the best choice or not. I would be interested in getting something that was as useful and looked as nice as Borland's.

I would be happy to pitch in. What I think we would need is some templates that would help others create the pages correctly. Maybe generate some and we can see where we go from there.

Shane

>> 05/19/00 09:49AM >>>

Hello...

I'm new to this mailing list, but I'm a long-time Pascal/Delphi developer (about 15+ years with Pascal, and about 4+ for Delphi) and I'd like to pitch in a little bit with Lazarus to try and help get it going.

Before I start jumping in with some new components, I need to get a little better aquatinted with the existing code anyway. What I'd like to do is try and start a "Lazarus" documentation effort for each one of the objects in a manner similar to the Borland help documentation, but with some much better examples and explanations for the properties, methods, and events. I would envision this as a series of web pages, but I'd like to also know who else is also working on anything even remotely like what I'm discussing. I know that this is somewhat automated by pulling stuff from the unit files themselves, but this is also limiting because the cross-links aren't usually present and sometimes the explanations are not quite as well done as they could be.

PM Michael A. Hess wrote

My 2 cents.

And mine as well...

As a possible IDE extension (granted, way in the future) it would be nice if there were a way to select a declaration and see the external document file. Perhaps a hover (as in hints) or a context menu item, or even a seperate window. I realize this isn't easy, but it would be very useful.

Jeff.

<Snipped>

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. 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.)

Any other ideas?

You mentioned in the past that you were going to document 2 files so we can see an example on how to document the files so PASDOC can use them. Can you do this and use the external documentation feature? I know you have nothing better to do (joke). :-)

I would be interested in how this external file thing works....

Thanks
Shane

>> 05/19/00 02:58PM >>>

My 2 cents.

I would like to see us continue with PasDoc if at all possible. Currently we are one of the major users of PasDoc. So that being the case if we need a feature it is an easy matter to ask the developer and he adds it. Currently it provides HTML and LaTex output. It would be great if we could get XML output. Then we could manipulate and combine that into a real manual at some later date.

Currently the output from PasDoc seems limited due to the fact that virtually on comments are available in the code. More comments better documentation. I think the best way to attack it is to use the external file for the comments. I find that excessive comments in the source code makes the code harding to read and edit. Placing the comments in an external file will let you be as verbose as you wish since it will only be used by the documentation tool. If we generate the documentation from the source code then we know that the documentation is as close to the current code base as possible. If it is done as a totally separate effort then it can become stagnate and get further and further behind the actual coding effort. However if comments aren't add the same thing will occur.

I would also like to automatically generate the documentation on an almost daily bases. I have not implemented it yet due to the fact that there are next to no comments available making the documentation very limited in usefulness. If we start get some more comments and examples included in the comments file then I can automate the documentation build and it will be on the web site daily with the latest information.

I'm sorry, but I jumped in a bit too soon with that message. Yes, I'd like to go through the comment blocks and add some documentation for now anyway directly in the code (which is a good idea in the first place) and try to keep working though the objects.

For at least right now, is there a unit or two that is (relatively) stable that won't mess somebody else up by checking it into CVS?

Nevertheless, probably the best is to enhance the existing comments. Pasdoc supports pulling the explanations from an external file.

It is therefor quite feasible to work on the documentation in the separate files, and just insert the needed comments in the source files, so the structure of the documentation is generated correctly.

It would of course be nice if pasdoc could check for each method/field/whatever whether it can find a comment block in the used textfiles. This would obliviate the need for the comments in the sources.

In any case I think that it is a requirement to use pasdoc, because it is the only 'structured' way of handling the generating of documentation.

Michael.

Pasdoc already does that. HTML and TeX. Just add XML, and then you're off.

Go ahead. I would prefer if you extended pasdoc so it can produce XML. That would be by far the simplest.

Michael.

Hello...

I'm new to this mailing list, but I'm a long-time Pascal/Delphi developer (about 15+ years with Pascal, and about 4+ for Delphi) and I'd like to pitch in a little bit with Lazarus to try and help get it going.

Before I start jumping in with some new components, I need to get a little better aquatinted with the existing code anyway. What I'd like to do is try and start a "Lazarus" documentation effort for each one of the objects in a manner similar to the Borland help documentation, but with some much better examples and explanations for the properties, methods, and events. I would envision this as a series of web pages, but I'd like to also know who else is also working on anything even remotely like what I'm discussing. I know that this is somewhat automated by pulling stuff from the unit files themselves, but this is also limiting because the cross-links aren't usually present and sometimes the explanations are not quite as well done as they could be.

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.