[Lazarus] Missing Documentation
pascaldragon at googlemail.com
Thu Mar 1 08:29:52 CET 2012
> 1. Are they created by a tool or hand edited? what are the tools used?
Source documentation is generated using FPDoc. The tool makeskel parses
the source file and generates a xml file which the documentation will
Documentation for e.g. IDE usage is done in the Wiki.
> 2. Is there some page where the original docs are created?
Sorry, I don't understand what you mean here.
> 3. Are they text files that are stored under version control?
As already written on the FPC list, the files are XML files available in
> 4. Is there some page where previous versions are available?
Released versions are available through downloads and a finer grained
control is available through Subversion.
> 5. How is it structured, what are the formatting rules? Is based on
> standards like DocBook etc?
It's a custom XML format.
> 6. How much of the documentation is generated from the source code? Is
> information about input and output parameters, and a few lines about its
> usage and gotchas generated from source, or does all procedures need to
> be documented by hand using FPDoc? Graeme mentions IPF that in his view
> does a better job? Do other preferably Pascal based projects use other
> tools with which they have had more success?
The skeleton is created using a tool, the rest is up to the persons
documenting the code.
IPF is only one of the possible formats that the XML documentation can
be generated to. Other examples are TXT, RTF, PDF, HTML and CHM (the
latter being supported by the text mode IDE and in Lazarus through lHelp
(which is distributed with Lazarus as source)). The text mode IDE can
also use IPF files.
> 7. Are there other tools that can do a better job, such as Jira, Github etc?
GitHub has nothing to do with generating documentation. I don't know
about Jira. Also FPDoc is working quite well, also it's under ower
complete control, so we don't need to wait for some third party
developer to extend the syntax his tool understands if we extend FPC by
another language feature (hint directives and generics are nice examples).
> 8. I assume that docs are generated by some build tool once created.
> Does the submitter compile the docs on their own system and test that
> they are fine before getting them committed into the repository? Are the
> tools used identical (I see messages in the mailing list about
> contributors being using different versions of the tools)?
They are built locally. There should be no major differences if they are
built on different systems if the tools are setup correctly.
More information about the Lazarus