• WantedFeatures

Wanted features

If you are missing anything from PasDoc, add it to this list. Alternatively, you can submit your requests to PasDoc feature requests tracker.

• Additional special tags and more

  • I'm using a wide range of several documents processors (JavaDoc, CppDoc, Doxygen ect.) for different languages. One common thing uniting these programs is their ability to describe more informations about the document, its relationship to the whole API ect. To make it short: I'm missing special tags like @version and @since. Both tags are commonly in use and should be introduced to PasDoc. It's very hard to find out when a unit ect. had been introduced to the API or had been changed in depth without such tags. Such informations including @author should appear at the top of the page and not at the bottom. Last but not least there should be a switch in the GUI turning on/off opening a new HTML page in the browser. There is the fabulous key F5 for refreshing a page's content when openend once

• Comment grouping

  • Would it be possible to set a command line option for PasDoc to group related identifiers that are documented by one comment:

       1 //Similar Procedures
       2 procedure ProcA1;
       3 procedure ProcA2;
       4 procedure ProcA3;
       5 
       6 //Another Set of Similar Procedures
       7 procedure ProcB1;
       8 procedure ProcB2;
       9 procedure ProcB3;
    

    • My main reasoning is that each procedure does not necessarily require individual documentation and it would be helpful if one comment caused them to be grouped together in the HTML output. Just a thought.

      • I fully agree and I plan to do this by @groupBegin, @groupEnd tags. See here: http://pasdoc.sipsolutions.net/MichalisKamburelis#head-37b668d7adfade5942c8c734e62a83100e67327f . I don't think that we can do it without any @-tags (like your example), because this would tend to group too many things. – MichalisKamburelis

• "support to format multiple return values"
  • It would be really nice if @returns(...) could output return codes and descriptions in a more structured way - like the @params tag already does. Most intuivie way would be to allow more @returns tags for a single method, i.e. @returns(S_OK if successful) and @returns(E_FAIL if an error occured). S_OK and E_FAIL should be formated as 'label' of the return code and all following words are the description.

    • Seems like a good idea. But for backward compatibility, new tag should be named different, like @returnsValue. Old @returns with old behavior should stay. – MichalisKamburelis

• improve comment detection support
  • comments should be extracted if they are placed only right before declarations:

       1 Foo = class
       2   FBar: integer; //some comment
       3 public
       4   constructor Create;
       5 end;
    

    in this case "some comment" would be attached to Create and its' not very good

    • Probably rejected. There are people who prefer to write code like

         1 type
         2   Foo = class
         3     { My Field1 }
         4     public Field1: Integer;
         5     { My Method1 }
         6     public procedure Method1;
         7   end;
      

      So it's not so obvious that comments before "public" keyword shouldn't be assigned to the next field/method/property. The same argument goes for some other keywords, e.g. "type", "const", "var". Some people write code in such way that they would prefer having their comments (placed before a keyword) still assigned to the following item. Therefore we can't implement it. Unless it would be activated by some command-line option, like --assign-comments-rigorously. But

      1. In the typical situation you can just place  { }  before an item that should stay without documentation

      2. In the good documentation most items have some documentation comment

      3. There is other method to prevent pasdoc from using unwanted comment: see CommentMarker

      So I would say that there is no real need to implement this. Any arguments anyone ? – MichalisKamburelis

      • I think, that above mentioned cases can be easily distinguished by the type of the comment: is it placed after code or on the separate line. It may be significant if you are going to implement inline comments one day. – Konstantin Pastbin

        • I feel uneasy with treating differently comments that are placed after code and on separate line. This is against Pascal (and many other languages) free-syntax rules, that say that the amount and kind of whitespace doesn't matter.

        • As for inline comments, look at my answer to inline comments lower on this page (in "Duplicate requests" section) – I like the idea of inline comments, but I prefer to recognize them by the special character "<". So in that case I also don't want to introduce a difference between a comment "after code on the same line" and "on separate line". – MichalisKamburelis

• DocBook output ?

• use a Delphi project (.dpr) file as input and process all files listed there

  • This depends on doing WantedFeaturesParsingImplementation (at least partially, just to parse the "program" keyword + program name + ";" + the uses clause (with the unit names optionally followed by "in" + (string) filename). It's quite easy actually – MichalisKamburelis

• Delphi IDE-Plugin to build documentation for the current editor window on the fly and display it (should work great using the caching algorithm)

• Delphi IDE-Plugin to show the documentation of a unit on a separate tab page of the editor window with clickable links to the actual implementation. (Yes, I am dreaming )

• support for EnvironmentVariables in addition to CommandLine options, e.g. INCLUDE

• allow excluding classes from the documentation (or maybe make them invisible, e.g. make their members appear to belong to all descendant classes, this would be convenient with pseudo templates (TemplateDocumentation)

• optionally calculate correct line numbers and put those into the output
• make caching work properly by putting the unit file's timestamp into the cache file and comparing it with the current on-disk timestamp. This should also expire any units that use this unit (which will automatically reparse descendent classes of classes in this unit that are defined in other units).
  • implemented half of this (expires units, but not units that need the expired unit)
  • implementing re-parsing is harder than it appears because units are not parsed in dependency order
• ship files with defines from Delphi, Kylix and FPC (maybe even GPC) for different platforms.

  • If someone wrote his source code, then he already knows about the defines that he used (and that may be relevant to pass to pasdoc). In other words: It's a job of compiler writers to document what symbols are automatically defined by their compilers. After a programmer already wrote a source code using such-and-such compiler defines, this programmer already knows about these defines... So these files would only be useful as a comfortable data, for people too lazy to grep their own sources for $ifdef On the practical side: making such files complete is almost impossible, because each compiler/compiler mode/OS/processor/etc. results in a different set of defines, and it's tiresome to document them all (and maintain such documentation to keep it up-to-date with new compiler versions!). That said: if someone really wants to take a shot at preparing such files, go on, you are welcome to add them to this wiki. If you will do it well, we will include them in pasdoc. – MichalisKamburelis

• ability to deal with files that have the same name but are in different directories. How does one distinguish those without having search paths?

• ability to link external documentation that was created by PasDoc (some mapping file class/function -> html file must exist for this)

• delete the first and/or last charater of each line in bloc comment. Usefull if you want your doc in source code look better. Look Here for more description

• a CommandLine options --file AFilename where AFilename is a config file that contains all parameters to use in addition to the command line. This is usefull if CommandLine options are very long and/or to distribute them with the project.

  • I don't see much reason for this. If you want such thing then you should use some script (like bash, sh (or even bat if you must)). Otherwise, pretty much every command-line program in the whole world would need such option. MichalisKamburelis.

• Generating doc as XML format. After that you can use a XSLT processor to generate the final format. The code is parsed one time and it's possible to generate all types of docs! –GarfieldFr

  • Yeah, XML would be nice, and it's on my TODO list. But things are still too messy now in html and latex generators to actually start implementing a new generator. But XML output will definitely be done one day.

    That said, I don't think that we ever should use XML as an intermediate format for generating the other output formats, like html and latex. Using XML wouldn't give us any benefits over the current situation, where we use a generated tree of TPasItem classes. XML output would be mainly useful if you would like to implement other programs, separated from pasdoc, that do something (related to generating doc or not) with the information generated by pasdoc. Oh, and fpdoc also has XML output. I didn't try its XML output yet, but it would be nice if our XML output would be similar to fpdoc's XML output. Oh, and fpdoc input format is also XML. So this is another version of XML that I'd like to implement, and actually right now this is the most important output format for me to implement one day – see my homepage on this wiki for more info about this. – MichalisKamburelis

• WantedFeaturesParsingImplementation

• Generating Labels and URL in Graphviz files to link images classes files in HTML (or HTML Help). Look How to do in Clinet-side image map. With this feature, it's possible to navigate in units/classes doc from graph! –GarfieldFr

  • I started doing this, now in GVClasses.dot and GVUses.dot graph nodes have proper href= attribute. So we can process them with

    dot -Tcmapx GVUses.dot
    dot -Tcmapx GVClasses.dot

    Now we have to use output of above calls from dot inside HTML files, like GVClasses.html and GVUses.html, and we will have client-side image maps assigned to graphviz images. This would require automatically calling dot program – this indeed should be done, I'll have to investigate how to implement it nicely, so that pasdoc will not fail if dot can't be executed. This should also remove some mess with four CommandLine required to use graphviz – only two CommandLine options shoud be needed for this. Also, you can process files to svg format, then you will have links included directly in svg file, and then we don't have to make client-side maps in HTML at all. Unfortunately, I don't know of any WWW browser that fully supports svg (allowing user to follow URLs from nodes) at this time... But pasdoc should not lose the possibility of using svg instead of some pixel-based format of images. – MichalisKamburelis

• It would be nice to be able to skip "n" characters from the begining of the comment at least for those making their documentation in ModelMaker that adds a special signature to the begining of the comment.

  • Can you describe in more detail what "special signature" is added by ModelMaker (bear in my mind that I never used ModelMaker and I'm completely alien to it) ? Maybe what you want is already possible via --marker <marker> CommandLine option, see CommentMarker page ? It would be easy to add some CommandLine option like --skip=n, but this is rather "brutal" feature, so I would like first to make sure that it's really needed in some practical case. – MichalisKamburelis

• It would be nice to have an Include directive able to include ASCI text, images or html in a point of a code comment. It would be very nice if this include directive also could build the name of the file to include by some kind of rule to the name of the class (include ModelMaker exported diagrams).

  • For me, this splits to a couple of sensible requests:

    • Done I think that for including images, we should create new pasdoc tag, like @image(filename).

    • Done For including text at the point of description, it could be useful to create a tag like @include(filename). Given file would be always interpreted as being written using normal pasdoc descriptions syntax (@-tags are interpreted, empty line means a paragraph, user can always use @html / @latex tags to force direct markup etc. – just like IntroductionAndConclusion content).

    • Then we can allow user to use @classname, @name and similar tags as part of filename. E.g. @include(@classname.txt) before a class TStream would be equivalent to @include(TStream.txt).

    – MichalisKamburelis

• Block "exclude tag" which allow exclude block of variables, constants, procedures from documentation. In some case is hard to write @exclude many time. I thing that tag as "@exclude_start" ... ... ... "@exclude_end" will be useful.

  • Seems fine for me. Although I think that names should be @excludebegin and @excludeend (because begin/end pair is familiar to Pascal programmers, and we shouldn't use _ in the middle of the tag because 1. currently we don't allow _ in the middle of tag, so e.g. @name_some works 2. we have @classname instead of @class_name 3. in general Pascal programmers don't use _, they rather use CamelCase, so people would be more comfortable to write @excludeBegin and @excludeEnd than @exclude_begin and @exclude_end). – MichalisKamburelis

• Allow tag expansion in another tag. For expamle: Parent for this class is @link(@inherited)
  • Note that this is already done in many cases, i.e. tags are expanded within other tags, e.g. you can use other @-tags inside tags @code, @raises, @returns, @bold, @italic, @abstract... However it's indeed not done for @link tag yet. That's because current expansion of @inherited and @name and such wouldn't be suitable for @link tag (because @inherited and @name add some presentational tags around returned name).

    As for your example, @link(@inherited) is not needed, you can already write just @inherited, this already produces a linked name. But indeed writing things like @link(@inherited.MethodName) would be a nice feature to have. So I agree with this request, this should be made possible. Moreover, some request above (see @image and @include tag) also could use of this feature. – MichalisKamburelis

• Make multi-line //< comments glob together like // coments do. Or even a //< line followed by multiple // lines.

  • //< followed by // lines cannot be glued together – lines // are supposed to be attached to the next item. So

       1 procedure Item1;
       2 //< Description of Item1.
       3 // Description of Item2.
       4 procedure Item2;
    

    must be parsed correctly.

    That said, glueing multiple adjacent //< lines is sensible. Patches to implement this are welcome. – MichalisKamburelis

• One item which would add a lot of value to PasDoc would be to include a means of documenting the functions/procedures that can be called on a particular class. atm, PasDoc will list all functions/procedures that a particular class introduces - but there's no way of finding out what it's really capable of. For example, if you have:

• type
    TClassOne = class(TComponent)
    public
      function MethodBase(): integer;
    end;
    TClassTwo = class(TClassOne)
    public
      function MethodSubclass(): integer;
    end;

• The page for TClassTwo will list "MethodSubclass", but give no indication that "MethodBase" can also be called on this subclass. This makes working with PasDoc's output a lot more difficult than it needs to be; in order to find out what methods you can call on a particular class involves looking at the documentation for that class, then the parent class, then that parent's class... It would be extremely useful if a layout similar to that which Delphi's help file offers would be implemented as an option, which would give an at-a-glace view of what any given class offers.

Requests closed

Features done

Requests that will be done will be added to this section.

• some parameter that can link a .txt file as general documentation, which is written to the beginning of the output. i.e. the start page for .html output or the first pages for .tex output. this could be used to write some general information about the project, including how to get it working, what is required to compile it, etc. of course, format tags would be nice.

  • This would also close RFE 964800. This is implemented now, see IntroductionAndConclusion. RFE 964800 closed.

• Wanted @see(Name) tag, which generate "See also" section and link to Name.

  • Implemented as @seealso tag – MichalisKamburelis

• "preformatted comments" command-line switch
  • While HTML conventions are good if one wants to place a long continuos text in a comment, but it's not so good when it is needed to retain original formatting (where each linebreak is treated like it is). Blank lines in such cases are consuming too much space sometimes.

    • Probably already done: It seems that what you need is already implemented: see PreformattedTag. Also see LongcodeTag (specifically for Pascal code). You can also always use BrTag to force line break at some place. I don't think that introducing command-line option to treat all comments like preformatted would be good. After all, WWW browser or LaTeX page width should usually determine page width. In other words, @preformatted and @br tags should be used seldom if you want your documentation to look good. So command-line option that makes all comments treated like preformatted would do no good. – MichalisKamburelis

      • No answer from submitter within a month, so I'm moving this to Done. – MichalisKamburelis

Duplicate requests

Duplicate requests (that request something that was already requested in some other place) are moved to this section.

• It would be very nice if you have the option to get method description from the Implementation part as most of the times Interface part has only a OneLiner description and the real Description is on the header of the implementation of the method.

  • I would argue with "most of the times" statement... It heavily depends on one coding style, and many programmers, including myself, tend to put comments in the interface section. Anyway, I don't say that this shouldn't be implemented. It's already requested on page WantedFeaturesParsingImplementation, so I'm moving this request to Duplicate requests section. – MichalisKamburelis

• include a Delphi project file (*.dpr) to the files to parse (useful for instance for library interfaces)

  • This is also mentioned at WantedFeaturesParsingImplementation. I'm moving this to Duplicate requests section. – MichalisKamburelis

• extracting of comments located in implementation section

  • The one may prefer to include brief comments in interface declarations and more detailed in implementation. It would be good if they were merged by PasDoc. It's also the case when I need to document functions's some local vars, procs, etc. It simply can't be done in interface.

    • Duplicate. This was already requested in WantedFeaturesParsingImplementation. Patches are welcome. – MichalisKamburelis

• support for inline comments (like the ones in JavaDoc)

  • now I have to comment out vars like this:

       1 //very important variable
       2 var1: string;
       3 //another important var
       4 var2: integer;
    

    it would be much more convenient to do it this way (especially when commenting a long list of vars / fields in a class):

       1 var1: string; ///very important variable
       2 var2: integer; ///another important var
    

    I.e. in this case we should take comments, lying _after_ declaration of course it needs special tag (like triple slash used in example). Or you can better do it by distinguishing comments taking the whole line (let's say, before declaration) and the ones that are placed after some code (let's say, after declaration).

    • Duplicate. This was already requested by RFE 803026. There the submitter suggested using "<" as the special character (i.e. your example would be like

         1 var1: string; //<very important variable
         2 var2: integer; //<another important var
      

      and I would prefer using "<" than what you propose (using triple dash "/" or automatically assigning comments on the same line). That's because "<" looks sensible also with other types of comment, and this would allow me to use this feature in other situations. E.g. I like to see the initial unit's declaration line at the beginning of .pas file. Using this feature I could write

         1 unit MyUnit;
         2 
         3 {< This is a documentation of MyUnit.
         4    It's possibly long, multiline,
         5    because I often put a lot of general
         6    comments about the unit here. }
         7 
         8 interface
         9 
        10 ...
      

      Patches to implement this are welcome. – MichalisKamburelis

      • This is implemented now, see WhereToPlaceComments section about "Placing comments after the item" – MichalisKamburelis

• Pure latex style vs wiki style: Provide english readable shortcuts for some of the tags that clutter sentences and confuse non-pasdoc users. For example (backquote)Clone could be equivalent to @link(Clone) - cuing off (backquote) preceeded by a space, rather than the apostrophe to prevent parsing mixups.

  • Duplicate: In general, "wiki markup parsing" is already a wanted feature. See this RFE and comments on MichalisKamburelis homepage about "More wiki-like syntax for pasdoc descriptions". That said, if we're talking about the @link tag: There already is a solution that allows you to avoid writing @link tags, see AutoLinkOption. – MichalisKamburelis

Rejected requests

Requests that are rejected for any reason are moved here. Of course, a reasoning why a given request was rejected should also be given here.

• It would be nice to have a RespectCRLF switch to allow less clutter in code comments. The switch just makes the documentation respect the Carriage Returns present in the source.

  • Pasdoc treats line endings inside your comments just like any other whitespace, and this has a very good reason. All other documentation formats also do this – see e.g. HTML, LaTeX, many wiki engines. Line width should be determined by www browser window width or printer page width or something like that. There are workarounds (\\ in LaTeX, <br> in HTML, @br tag in pasdoc) to force line break, but they shouldn't be used often anyway, so there is no reason to make them more comfortable to the user. Human, writing documentation, should force newlines only when they have some real meaning: e.g. when you want to do new paragraph. And this is easily possible in pasdoc: just write an empty line (see WritingDocumentation). This not only makes line break, but this also produces additional vertical space between paragraphs. Summary: you can use @br tag to get line ending. But you shouldn't ever need to use this tag too often. So there is no good reason to make it more comfortable, by making some option to treat line endings in pasdoc like @br. – MichalisKamburelis

• it would be nice to have a AllowHTML switch that would permit HTML tags like <strong>xxx</strong> in the middle of the comments.

  • You can use @html tag to directly insert HTML tags into your documentation. You can't write directly HTML content inside pasdoc descriptions, because this can't be really nicely implemented. Even if pasdoc would only want to generate HTML documentation output, this would be troublesome: You would have to treat special HTML chars, like <, >, &, as a special characters inside pasdoc descriptions, and you would have to escape them. Moreover, the fact that you could mix pasdoc @-tags with HTML tags would mean that pasdoc must at least partially understand HTML, at least on a level of reliable HTML lexer (to avoid problems with catching @-tags inside HTML tags attributes and such). However, pasdoc tries to generate documentation not only for HTML. LaTeX is another output format, and more output formats will come. If you we would allow HTML tags inside your documentation, then we would have to remove them later when generating LaTeX documentation (or try to interpret them, like replace <b> with \\textbf{ for LaTeX – this is not really a reliable thing to do). As for <strong>xxx</strong>: you can use @bold tag that I just implemented to have some text formatted in bold (in HTML and LaTeX). In general, this is the way to go – in the perfect future world, you shouldn't need to use @html tag too often, because every sensible functionality will be available using pasdoc @-tags. – MichalisKamburelis

• define (by default) things like LINUX if PasDoc was compiled on Linux, or MSWINDOWS if it was compiled on windows etc?

  • I don't think that such behavior would be a good one. After all, if I'm using simultaneously more than one OS/processor, then I still don't want pasdoc output to be different, depending on under which OS/processor I executed my documentation generation script. That's because I don't want to provide different versions of documentation of my units – one version for people who use Windows, one version for people who use Linux, etc. – such documentation would be very tiresome if people would want to write cross-platform code using my units, because then you have to know the differences (if there are any) how given procedure behaves on each OS. So I rather want to provide one documentation for my units, that simultaneously documents behavior of my functions under all OSes. And this means that when I generate documentation for given unit, I want to always (no matter what OS/processor I use currently, and no matter what compiler was used to compile pasdoc) run pasdoc with the same symbols defined. That said, note that pasdoc_gui does this: default symbols defined for each new pasdoc_gui project depend on the compiler defines that were present when compiling pasdoc_gui. In case of pasdoc_gui, it's not a problem, because 1. every user of pasdoc_gui actually sees these compiler defines and can adjust them if he wants (and probably everyone will) 2. in the future, it will be configurable for user what default compilation options pasdoc_gui should propose when creating new project (none (like console pasdoc) ? the ones that were defined at compilation of pasdoc_gui (like it does currently) ? some user-defined set ?) – MichalisKamburelis

• "compatibility with older pasdoc versions"
  • In older pasdoc versions it was possible to use blancs between tags and brackets, i.e. @param (someparam someparamdescription). This does not work any longer since a while, so always I check out a new version from cvs repository, I have to do some modifications to assure compatibility. This is just a simple addition but it is really useful in my opinion because it makes comments within the code better readable because of this blanc.

    • Probably rejected: AFAIK it was never officially allowed to put spaces between tags and brackets. I never knew that it was possible. So it worked by accident. I guess that it stopped working during 0.9.0 release, when TagManager was implemented. This behavior is safer, so this is going to stay. It's a pity that we broke compatibility, and I'm sort of sorry about that, but this will not be changed now. You can't put spaces between tags and brackets. Side note: you may be interested in TagsParametersWithoutParenthesis feature, then you may be able to sometimes avoid writing parenthesis at all. – MichalisKamburelis

      • No answer from submitter within a month, so I'm moving this to Rejected. – MichalisKamburelis

• The ability to exclude comments from the pasdoc parsing, for example  //! comment  or  {! comment}. Currently a  {}  on a blank line is needed to be inserted anywhere comments are not relevent to the documentation, otherwise they bind with whatever code is below them. I feel most comments should be in the docs, so I would prefer to be able to exclude the comments that won't be instead of use markers to mark every comment that should be - //*< on the end of every line can get excessive.

  • Rejected: Similar idea was discussed recently on pasdoc-main MailingList, see this thread: http://sourceforge.net/mailarchive/forum.php?thread_id=9166433&forum_id=4647 and, in particular, my answer http://sourceforge.net/mailarchive/message.php?msg_id=14107333. In short, inserting { } before an item that should stay undocumented is better and not more troublesome than some "exclude marker" like ! in your examples above. – MichalisKamburelis