index.html

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

       <p>There is a quote out there (from <cite>Butler Lampson</cite> or
          <cite>David Wheeler</cite>):<br>
          <q>All problems in computer science can be solved by another level
             of indirection.</q> (often misquoted with "abstraction")<br>
          And, well ..., in anticipation of further problems I readily
          introduced several layers of abstraction. Surprisingly it does not
          seem that much slower, only about a quarter, but well, I guess,
          string handling is slower than I thought.</p>

       <p>Btw., if you don't see quotes around the above quotation, you are
          using a browser that doesn't comply to
          <a href="http://www.w3.org/TR/html4/">a nine year old standard</a>
          and the very base of the World Wide Web, as:
       </p>
       <blockquote>
         <a href="http://www.w3.org/TR/html4/struct/text.html#h-9.2.2.1">Visual
         user agents must ensure that the content of the Q element is
         rendered with delimiting quotation marks.</a>
       </blockquote>


<!-- Remember to change date below! -->

<!--
      <p>The Kylix users out there should be sure to load the new version of
         the ConvertForKylix.tcl.zip, I fixed some issues and there are also
         some changes (like the JPEG-Support).</p>
-->

<!-- Remember to change date below! -->



    <h2><a name="Request">Requests</a></h2>

    <p>Any feedback on <em>DelphiDoc</em> is welcome. Especially also on the
       different character encodings. In HTML you can set you own encoding in
       the options. But I don't know what has to be done in Windows help files,
       L<small><sup>A</sup></small>T<small><sub>E</sub></small>X
       files and PDF files to choose the correct encoding/font, mainly because
       I'm so fortunate to use a language where the default encodings
       (Latin-1/Windows-1252/ISO-8859-15) suffice.</p>

    <p>Feedback on parsing of the comments would also be appreciated. I know
       that no one has projects commented for this program, beside this one.
       But even generating the documentation with the options
       <a href="options.html#OptionTSectionExtractor"><code>DoNotSectionize</code></a>
       and
       <a href="options.html#OptionTJaddCommentData"><code>DontParseComments</code></a>
       enabled the comments (I hope most projects will have at least some kind
       of a comment) should be valuable, so I hope they are correctly
       found.<br>
       So any feedback on how these comments are inserted are welcome, i.e.
       &quot;Are they actually found by <em>DelphiDoc</em>?&quot;, &quot;Are
       there any special characters/words/lines that are not really part of the
       comment and should be removed?&quot; or &quot;Are there any errors with
       any special characters?&quot; and so on.</p>


    <p>Some basic statistics are gathered about the parsed source code,
       you can view them in the form with the source code (<code>F9</code>).
       These values are currently not saved and not included in the
       documentation. I'm actually thinking about how, when and whether to
       include it somewhere in the documentation and also what other
       statistics to gather. <strong>You</strong> have some suggestions?</p>

   <p>You may have noticed there is still something below the TOC (Table of
      Contents) on the
      <a href="http://delphidoc.sourceforge.net/">home page</a>, yes, I
      started a little ongoing survey. So if you want to tell me and anyone
      looking at the result how you use Delphi and what you need, there is
      your possibility. It consists simply of several questions with
      yes/no/maybe - radio buttons. Answering them will only increase the
      corresponding counters, so don't expect anything special.</p>


    <h2><a name="WhatIsThis">What is <em>DelphiDoc</em>?</a></h2>

    <p><em>DelphiDoc</em> is a program for automatic generation of
       documentation on a Delphi-Project. It is created with
       <em><a href="http://java.sun.com/j2se/javadoc/">Javadoc</a></em> in the
       mind, i.e. what <em>Javadoc</em> does for Java <em>DelphiDoc</em> should
       do for Delphi but better fitting to it.</p>

    <p>So the documentation is not limited to the HTML format, because in
       Delphi and Windows the Windows Help format and the new HTML Help are
       more common, and Windows Help files can be integrated in Delphi's IDE
       for easy accessibility. As the special character in the comments the
       tilde "~" has been chosen instead of at "@", because the at-symbol is
       used in the Pascal language, the tilde is not. But this character can
       also be redefined to any other. At the moment the documentation can be
       generated in the HTML (HyperText Markup Language) format, in the
       Windows help (.hlp-files) format and the new HTML Help format, in the
       L<small><sup>A</sup></small>T<small><sub>E</sub></small>X format
       or in PDF (Portable Document Format by Adobe) with some additional
       xfig-/wmf-files. Export to XMI to be used in UML-modelling tools is also
       possible, and last but not least it is also possible to generate
       diagrams (UML-like) of the parsed classes etc. and even to include them
       directly in the documentation.</p>

    <p><em>DelphiDoc</em>'s distinctive features are an extensive parsing of
       the source code and a division of the parser and the generator of the
       documentation, and there are also a lot of options to tweak the
       generation. The first means a lot of information is gathered and can be
       inserted in the documentation making it valuable even if there are no
       comments (really useful to get acquainted with unknown projects if the
       generated help file is integrated in that of Delphi). Very much links
       are inserted as a cross-reference leading from identifiers to other
       identifiers if they use each other.<br>
       The second leads to exchangeable generators for documentation. At the
       moment five generators can be chosen to create the documentation in
       the above mentioned formats. Some additional generators for special
       things are also available. The several options of the generators and
       "inline command"s inside the documentation make these even more
       powerful.</p>

    <p>The documentation is somehow focused on an object-oriented design, so
       on purely not object-oriented programs the generated documentation may
       be not that efficient/well structured.</p>





    <h2><a name="DotNet">How compatible is <em>DelphiDoc</em> with
                         Delphi 8+/.NET?</a></h2>

    <p><em>DelphiDoc</em> does not support .NET currently. Delphi 2005 for
       Win32 is also not fully supported, yet. Some features have been
       implemented, but without enough information available it is hard to
       implement everything save (the Delphi-compiler is the only true grammar
       of the language and I don't have it). There is a limited support for
       unit-namespaces. The new scopes "<code><b>strict protected</b></code>"
       and "<code><b>strict private</b></code>" are parsed, but the scope is
       only treated as the normal scopes without the
       "<code><b>strict</b></code>". Multicast eventhandlers (properties) with
       the attributes "<code><b>add</b></code>" and
       "<code><b>remove</b></code>" can now be parsed. The
       "<code><b>for ... in ... do</b></code>" can also be parsed.<br>
       Not supported are nested types, class constants and the file-namespaces
       only partially. This is mostly due to insufficient information, so any
       hints on this behalf would be helpfull.<br>
       Unicode source files will also not be parsed, while UTF-8 should be no
       problem. Although when generating some generators may corrupt the UTF-8
       comments and for others you may need to set the character encoding.</p>

    <p>Support for .NET will not be added in the near future. There are not
       enough information about it available and the changes to the language
       are quite extensive. Still some changes were made in that direction
       (removing Delphi 3 as a possible platform to compile
       <em>DelphiDoc</em>). Any concrete, detailed information about it would
       be helpful.</p>




    <h2><a name="KylixSpecifics">What do I have to expect when
                                 using <em>Kylix</em>?</a></h2>

    <p>Most changes on the binary are how you expect them. No generated
       documentation will be launched automatically after generation because
       there is no associated binary to launch them. Also Window help files are
       not automatically compiled (what a surprise), although it is possible
       to compile them with the help of
       <a href="http://www.winehq.com/">Wine</a>. And no WMF (Windows Meta
       File) files are created (WMF records GDI calls, of course there is no
       Windows GDI in *nix).<br>
       Symlinks of directories are not followed (is that even possible?) to
       avoid eternal recursion (or until the stack if full), but the symlinks
       may be defined by them self, that should work. Furthermore the wrong
       end-of-line character sequence may be used sometimes, i.e. #13#10
       instead of just #10, but that should never invalidate any file.<br>
       If you want to compile <em>DelphiDoc</em> under Kylix take a look at
       <a href="sourcecode.html">the notes about the source code</a>.</p>


    <h2><a name="Issues">Main Issues</a></h2>

    <p><em>DelphiDoc</em> does not support .NET currently. Delphi 2005 for
       Win32 is also not fully supported, yet. Unicode source files will also
       not be parsed, while UTF-8 should be no problem. Although when
       generating some generators may corrupt the UTF-8 comments and for others
       you may need to set the character encoding.</p>

<!--
    <p>Overloaded functions are not recognized when they are used (i.e.
       called). Always the first one ist found. So all other functions seem
       not to be used and the first one quite often. In general
       <em>DelphiDoc</em> doesn't handle identifiers in the same scope with the
       same name that well, this is only one example. Fortunately only
       functions are allowed to have the same names, and then they have to be
       tagged by the directive <b>overload</b>.</p>

    <p>Localization support is in the fledgling stages.<br>
       I think this would be another nice feature, but I have no experience at
       all on this subject. And I don't know a lot of languages and the
       different requisites. First support is now added but I doubt that it
       is anywhere near to being perfect or even usable in other
       languages. Any comments would be welcome.</p>

    <p>Variant records are parsed but not documented which identifier is in
       which variant. Any idea how that could be accomplished besides dump its
       whole declaration?</p>

    <p>All characters of identifiers are significant not only the first
       255.</p>

-->



    <h2><a name="Legal">Legal Stuff</a></h2>

      <p>This program is now distributed under the
         <a href="http://www.gnu.org/copyleft/gpl.html">GPL - the GNU General
         Public License</a> version 3. A copy of the GPL should accompany the
         release in the file "<code>LICENSE.txt</code>". Please also take a
         look in the file "<code>README.txt</code>" for the used libraries,
         that are part of this program (and release) and are distributed with
         other licenses.</p>


      <p>And a note on the generated documentation:<br>
         The generated documentation inherits its legal status from the source
         (code) it was generated from, i.e. if you wrote the source and
         <em>DelphiDoc</em> generates some documentation, you also have the
         copyright on the documentation like on the source.</p>



    <h2><a name="Contact">Contact</a></h2>

      <p>For questions, suggestions and so I would prefer if you use one of
         <a href="http://sourceforge.net/projects/delphidoc/">SourceForge's
         services</a> like the
         <a href="http://sourceforge.net/forum/?group_id=113456">Forums</a>,
         the
         <a href="http://sourceforge.net/tracker/?group_id=113456">Tracker</a>s,
         the <a href="http://sourceforge.net/mail/?group_id=113456">Mailing
         List</a> or the
         <a href="http://sourceforge.net/sendmessage.php?touser=1075015">private
         message facilities</a> there.<br>
         So far I can also be reached through email at
         <b><code>DelphiDoc&nbsp;@&nbsp;gmx.de</code></b> (sorry for not making
         a link for it, but I don't want to serve up another email address for
         spam on a plate for web crawlers, ... I get enough already), just be
         sure to use a meaningful subject for the mail so it won't get lost in
         all the spam I get, please include "JADD" or "DelphiDoc" in the
         subject, using a plain text mail (instead of HTML) will also decrease
         that chance.</p>

      <p><em>DelphiDoc</em> should be able to parse most of the correct and
         compilable programs, but there are some constructs that may raise
         problems (it's weird what's all possible in Delphi and then gets
         compiled). In most cases the line and column should be given when an
         error occurs during the parsing, of course, just like with the real
         compiler, the true reason of the error may be a few lines higher.</p>

      <p>Should an error occur, a description of the error and a relevant
         excerpt of the source code, or of the whole project in case of complex
         constructs, can be send to me by email.</p>

      <p>Best regards,<br>
         &nbsp;&nbsp;&nbsp;Gerold Veith</p>

    This page has been found at
    <a href="http://delphidoc.sourceforge.net/">http://delphidoc.sourceforge.net/</a>.<br>
    <br>
    <div align=center><small>Last change: Saturday, the 5th April 2008,
                                          15:00 GMT +0100;
                             Page created with Delphi-Text-Editor;
                             Optimized for
                             <a href="http://validator.w3.org/check/referer">HTML 4.01 Transitional</a></small></div>
  </body>
</html>