I need a code documentation tool similar to javadoc or c# xml doc for delphi code. What is the best tool? I prefer a technology, which is in the future compatible to the Microsoft sandcastle project.
Take a look at SynProject, an Open Source tool written in Delphi.
It was designed to handle a full documentation workflow, from specifications to release notes, including tests, architecture and design; and of course there is an integrated Delphi parser to generate architecture documentation from existing Delphi source code.
For the architecture document, the source code can extract comments (ala PasDoc) then embed this text into the main Architecture document (with class hierarchy diagrams and unit dependencies).
You write a plain text file using a wiki-like syntax in a dedicated text editor, then SynProject creates well formated Word documents from it. Some Wizards are available to access the content. But since it's stored as plain file, multiple programmers can write on it, using any SCM tool (SVN, Fossil...).
For instance, I currently use it for writing maintenance documentation for a huge and old Delphi application (about 2,000,000 lines of code written in Delphi 5 and 6), with no prior available documentation. You describe the changes made to the code (by quoting the unit/class/method), then the tool will update all documentations to reflect and trace those modifications. SynProject was designed to be compliant with some very "delicate" regulation rules (IEC 62304), but can be used for any project due to its unique "flat" design.
Note: I'm posting this a long time after the question, because SynProject was not existing at this time, and can be worth looking at. This thread has been defined as a reference for that question.