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.
Related
I would like to write a syntax highlighting editor extension for VS 2019 in C++ (nothing else), are there any samples to get me started?
I can only find one example extension for VS 2019 written in C++ and it consists of a subclass with no explanations of how to do anything AFAI can see.
I believe I need a language editor extension, but am not 100%
The language it needs to highlight is similar to assembler.
If this was VS6, I might have just used the custom keyword colouriser.
I would like to write a syntax highlighting editor extension for VS
2019 in C++ (nothing else), are there any samples to get me started?
In current VS IDE, Microsoft does not advocate writing extensions in c++.
As Microsoft recommends, current extensions are more likely to use c# rather than c++.
Although some VS SDK APIs are probably written in c++, but the interfaces are still called using c#.
However, there is only one c++ project template called vspakcage
But this project provides various background services for VS IDE . It will only be loaded when needed. So for you to add the syntax highlighting feature permanently, this project is afraid of lacking.
Besides, there is no official documentation to guide the writing of the c++ project.
Suggestion
You can try to write such extension in c#, and you can refer to this official document and this.
In addition, if you still want your feature, I suggest you could suggest a feature on our User Voice Forum.(click suggest a feature). Then you can share the link with us here and anyone who is interested in this feature will vote for you so that it will get Microsoft's attention.
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 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)
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.
I'm new to developing in OpenLaszlo, and have tried Eclipse (hoping for decent code completion), but found it far too heavy for my tastes. fell back to using Textmate, but the bundle for OpenLaszlo is terribly out of date.
Any suggestions? or should I just roll up my sleeves and write a new bundle for Textmate?
I personally use SpketIDE as an Eclipse plugin. It has some code completion, good syntax highlighting.
I use VIM for this. The VIM mode that ships with OpenLaszlo recognizes both the XML tags and the embedded JavaScript. Of course, if you're not already a VIM user, it's a big project to dive in.
If you use a texteditor or XML editor with support for XSD schema, you can generate a custom XSD file of your application using this OpenLaszlo Schema Generator tool. The tool uses Ant to generate the schema file, which then can be used by the editor of your choice.
We used Visual Studio. And we used it just as a great XML editor.
I also used Notepad2 because it is very lightweight and has syntax highlighting.
I've been using Notepad++ with the XML language chosen (since Open Laszlo is basically just XML and javascript). Simple, but effective and free.
I wouldn't have added it otherwise, but since its arch-enemy VI(m) was mentioned:
Emacs
is worth listing. :)
Without knowing much about OL, I am pretty sure one of gazillions of modes it has provides some level of support for your editing needs.
I've been developing in OpenLaszlo since 2006. I currently use NotePad++ with .lzx files set to be interpreted as XML files, this allows the code to be highlighted well in different colours for the different parts that make up OpenLaszlo code (XML nodes, JavaScript/AS3, etc.).
You can find NotePad++ at:
http://notepad-plus-plus.org/
it is free.
I just test my application by loading it into a web browser page.