0

Possible Duplicate:
Code documentation for delphi similar to javadoc or c# xml doc

I have been utilizing the Documentation capabilities of RAD Studio Delphi XE2 across most of my global source (libraries such as business rules, components/controls, etc.). This places some commented text just before the declaration of various things in your source code, like so:

type
  ///   <summary>
  ///     This class is used for this and that.
  ///   </summary>
  TMyObject = class(TObject)
  ....

or even

/// <summary>
///   This function does this and that.
/// </summary>
/// <returns>
///   This is the result of what DoSomething produces.
/// </returns>
/// <remarks>
///   DoSomething is only a sample function for demonstration purposes.
/// </remarks>
function DoSomething: String;

The main reason I've been doing this is so that when you hover over a symbol, when it shows the insight, it will include this documentation text with it. For example, in a completely separate unit, hover over the text DoSomething wherever it's used and it will show you a hint box containing the exact text written in this documentation.

Hint: press either Ctrl+Shift+D or Ctrl+Alt+D (I've seen both those on different PC's) and it will open a window to make things easier. I stumbled across this when pressing Ctrl+Shift+S to save but accidentally hit D.

What I would like to know is how can I export this documentation to a CHM help file? I would like to make a help file linked to my library so a developer can use F1 in the code and see an explanation of what the code does. Just like the standard Delphi source documentation (and most other languages).

Community
  • 1
  • 1
Jerry Dodge
  • 26,858
  • 31
  • 155
  • 327
  • Do any of these other solutions in the duplicate explicitly utilize the XML documentation which I demonstrate in my question? Or do they require entirely different means of creating documentation? – Jerry Dodge Jun 10 '12 at 02:02
  • My point is, as stated in the question, I already have a majority of my source documented using this format - which seems to be somewhat a standard in XE2 (since hovering over symbols show this info). I need to be able to use what's already here, and keep this one source as the only source. It's difficult to maintain the same documentation in two different places. – Jerry Dodge Jun 10 '12 at 02:15
  • Just as an informational point: A ".CHM help file" is actually called an `HTML Help File`, and the "source documentation comments" are `XMLDoc` or `XML documentation`. – Ken White Jun 10 '12 at 02:43
  • 1
    They scan your code and do use the comments to generate a starting point. I just remembered one more commercial thing to try: http://www.doc-o-matic.com/features.html -- I think it's exactly what you're looking for. – Warren P Jun 10 '12 at 02:44
  • @WarrenP If what I explained above is called `XMLDoc` and if doc-o-matic supports `XMLDoc` then that would be a perfect solution :D – Jerry Dodge Jun 10 '12 at 02:48
  • 1
    That window you stumbled across with Ctrl+Shift+D is the DevJet Documentation Insight plugin that's now bundled with Delphi. There's nothing available yet but look at the second comment on [this page](http://www.devjet.net/support/whats-new) and Paul from DevJet says they're working on a tool to generate external documentation in several formats directly from the source code. Also since you're a big user of source code documentation I recommend you buy the v2 upgrade for your Documentation Insight plugin. – LachlanG Jun 10 '12 at 03:24
  • My first instinct was to recommend Microsoft SandCastle, but upon looking further I don't think that exactly what you're looking for is available yet. But there is a nice alternative called SynProject as explained in this thread: http://stackoverflow.com/questions/236047/code-documentation-for-delphi-similar-to-javadoc-or-c-sharp-xml-doc – Nickoli Roussakov Jun 10 '12 at 01:01
  • @WarrenP you have mentioned that Help & Manual supports source code documentation, and can scan the source code and extract comments? Is it right? still true? – Masood Nov 02 '15 at 12:55
  • I think this is no longer true. Deleted my prior comments as there is nothing in the H&M documentation that refers to this any more. Instead check out http://www.doc-o-matic.com/ or http://synopse.info/fossil/wiki?name=SynProject – Warren P Nov 02 '15 at 15:12

1 Answers1

2

It's not a CHM file but if you use Delphi Enterprise or higher the IDE has the ability to produce documentation using your properly formatted source code comments.

LachlanG
  • 4,047
  • 1
  • 23
  • 35
  • Are you referring to the documentation generation feature (part of the modeling functionality) that I linked to in my answer @KenWhite? If so then according to the XE2 feature matrix it's Enterprise and above only (I don't have access to Pro to confirm that though). If it's another feature you're talking about can you please link to it as I'm interested in taking a look. Thanks. – LachlanG Jun 11 '12 at 01:08
  • Actually, no. (I'm glad I didn't downvote. ) The link you provided is actually functionality *I* never knew existed. I'm still not sure that's what Jerry's looking for (the question seems to refer to converting XMLDoc comments to HTML directly, and XMLDoc support is what I thought your answer referred to), but thanks for the info. I like learning things I didn't know. :-) – Ken White Jun 11 '12 at 01:12