I assume that XML and Delphi Documentation Guidelines are becoming the de-facto standard for source-code documenting comments. That is good. The bad thing is that I cannot find any Delphi documentation generator (free or commercial) that fully supports these standards (for example Doc-O-Matic Express does not support <list> tags).
The question is: what XML documentation standards and Delphi source code XMLDoc documentation generators are ready to use now?
(You are asking two questions. That's probably why you are getting no answers.)
On the tools front, take a look at these previously asked questions:
IDE Plugin for XMLDoc
Code documentation for delphi similar to javadoc or c# xml doc
I would check these products:
doxygen
NDoc 3 (but maybe it requires access to .Net assemblies - then it will not work)
Related
I learned most of my haskell knowledge by browsing though the Haskell docs with source code http://hackage.haskell.org/package/base-4.2.0.1/docs/Data-List.html#v%3Ahead
But I couldn't find the source code of common F# libraries, I only found the docs on how to use them like http://msdn.microsoft.com/en-us/library/ee370406.aspx
Is there something like hackage for F#?
There is an open-source edition of the F# compiler and core library available on GitHub.
I am working with an undocumented, 100.000 lines Delphi 7 project and one of my goals is to create a software architecture document from the source code.
Can you give me any ideas on how to approach this?
These tools work with Delphi 7 and are of great help:
the UML tool ModelMaker
the refacotoring tool ModelMaker Code Explorer
the documentation tool Documentation Insight (as of august 2012)
UML diagrams are a great way to get an overview of structure. How well that overview is, depends on how well the structure is.
For taking over projects like these, I start with some basic documentation (often in MarkDown format, as that text based format is version control friendly, and generates nice HTML).
To get that going, it helps if the original developers or/and some base documentation are still there.
Then just start to:
fix bugs / apply feature requests
use ModelMaker to get a feel for overall structure
use ModelMaker Code Explorer as a refactoring tool
use Documentation Insight to document inside the source code (you can generate help files and web pages with the pro version, see feature matrix)
update my Markdown documents with any information that does not fit in the source code documentation well
Note you can put some documentation in using Model Maker Code Explorer, but it can not be exported as help files, since it uses a different documentation format than Documentation Insight.
So I agree with the comment by Jan Doggen (thanks Jan!): just start. Make sure you have the right tools to help that going.
Try running the source code through a newer Delphi version that supports UML modeling, then let it show you how different sections of code related to each other.
Understand will do the job. Free download includes 15 days evaluation which will be more then enough for what you need to document.
I am looking for a tool to generate Delphi source code documentation, and I want to give a try to Doc-O-Matic Express (which is free). Are there any guidelines for beginners how to use Doc-O-Matic Express to document Delphi source code (managing doc-o-matic projects, preferred docblock style, complete docblock syntax, etc) ?
Don't bother with Doc-o-matic settings right now. The express edition is command-line only.
Choose a comment style
Comment your code
Generate documentation (a default project is enough to start)
Verify you comment coverage
Doc-o-matic support JavaDoc and XMLDoc (or even kind-of native comments). The tool it-self will help only if your code is already comment, or if you want to comment directly inside its IDE.
If you like XML Doc or JavaDoc,
Doc-O-Matic does support both equally
well and all three styles are
supported when writing source comments
through the integrated editor back to
the source.
In this page you can found a doc which can be useful for you Delphi Documentation Guidelines. I used this guidelines to document my source code in this project.
I am seeking to understand someone else's code in Delphi 7 (I suspect that newer version have this built in, but I don't want to spring > $1k for the newest version).
Are their any (preferably FOSS) tools which will help me generate a class hierarchy diagram?
Actually, the class browser in GExperts is ok. Maybe not as good as the accepted answer, but just one of a great collection of tools
You can use ESS-model from SourceForge.
If you Load and .PAS (also .DPR, .CLASS,...) with some classes this program generate a Class Diagram and some Documentation. It's free and you can access to code source.
Regards
AFAIK ModelMaker 6.2 was included with Delphi 7, it's a UML tool. You can import your source code in it and generate class diagrams etc, I really don't remember anymore all of it's features, but I do remember that ModelMaker is awesome tool and it's sure worth a look.
Update: Model Maker (now MMX) is now free for all supported Delphi IDEs
You can take a look at our SynProject tool.
Synopse SynProject is an open source application for code source versioning and automated documentation of Delphi projects.
There is a pascal source parser, which will create all classes hierarchy documentation.
And it's much more than a parser: you can write the whole Specifications/Architecture/Design/Test/Release documents list in an integrated manner.
There are some tutorials, screenshots and resulting documentation sample in the above link.
Peganza's Pascal Analyzer (not FOSS)
Doc-o-matic's documentation generator creates class hierarchies. They have a free express version you can try.
How do people use XQuery and/or XPath 2.0 from Delphi? I've got MSXML v6.0 working from Delphi, so any sufficiently documented COM-implementation will work. What's your favorite?
My Favourite: I've always found that importing MSXML provides excellent support for all the XPath queries I've ever needed it for.
Close second: I'm not aware of any native delphi libraries that can match MSXML's depth of features however OmniXML provides great support for basic XPath queries and if you're not using expressions, for example, then it's a pretty good alternative.
Sadly, I do not think that there are currently any native Delphi XML Libraries that fully support XPath 2.0.
You can use the fast and opensource libxml2 library. There is a Sourceforge Project for free Delphi bindings.
I love OmniXML. It has a lot of supporting code and classes that extend its primary usage. You may also want to look at SimpleStorage that simplifies work with XML a lot.