|
Sorry...correction to table above
||Lakos||DoxyS
|Package|Directory
|Component|Unit
|
|
|
|
|
Hi
Very interresting thught you have there!
I could mention that one of the key reasons for starting the DoxyS project was the lack of a natural place to put the overview documentation for the code in a directory. At the time I was working in computergames and we had 500.000 lines of code with no documentation what-so-ever. I did not miss class/function documentation the most, but I really missed overviews of each of the 160 main- and sub-directories. Documentation outlining how to use the code in this directory and it fits into the grander picture.
But my own side ambition is to also use the page/dir concept for more than just documentation. I hope it could be used for also design documents and general documentation not necesarily code related.
To that end I would like to have a simple WYSIWYG editor for DoxyS wiki-like syntax. This would make it (for many people at least) nicer to use when writing larger designdocs etc., but still make it possible to open the documents in any simple text editor and make modifications to the text. This is convenient whne for example coding: A change in the code might call for a documentation a desig-doc change ... if you first have to find a Word document on a remote server you are likely not to get the correction into the design document.
It is important however to keep the wiki-syntax easily readable in plain text form. We do not want to reinwent HTML/XML style formatting which is really not user freindly to read in my humble opinion.
Also since we are using simple text files it is possible for many people to work together on the same document using version control systems like CVS or whatever you prefer. You can easily make diffs between versions and we could even make the WYSIWYG editor have a dual-diff-view-something allowing for easa merge even for non-technical people.
Well this got long! I hope it is not too far from what you meant, but anyways I really needed to get this out ..
Regards Martin Lütken
|
|
|
|
|
Thanks for the quick reply. Also, I wanted just to comment briefly on your statements.
1. I concur...class/function documentation is not where I like to start looking at a system and DoxyS does a marvelous job in extending documentation for subsystem or package level entities.
2. DoxyS really does allow us to integrate a design document with source code without making it painful (i.e. XML). The design and source really become one in the same; and when someone new to the system has a high level starting point to look at, it makes it easier to for them to dig deeper into the details (that is...the details they are individually interested in). This is a huge difference from other tools that I hope people recognize when they first start using DoxyS...one exception to this might be Headway ReView now called Structure 101 (but it's not free!).
3. Lastly, since DoxyS was designed to document the physical structure of any text content (not just logical source elements - class, function) it only makes sense that it would mesh well with physical software design techniques as presented by John Lakos. What I realize now is the similarities are not coincendental in nature but merely intrinsic to the problem of designing and documenting a system comprised of a heirarchy of physical entities.
4. With that said, I think DoxyS has potential of going further in this direction. Some ideas include making use of package and component diagrams. Making use of the Lakos metrics (CCD, NCCD, ACD, etc.) or even other object-oriented metrics (Martin's instability and abstractions principles) is relatively trivial but can offer a lot of insight into the high-level structure of a system. Lastly, but not so closely related is enabling pdf support for all of this great documentation we are now doing.
My response was much too "longer" than yours, but I just wanted to affirm my approval with what DoxyS has done and hopefully bring to your attention how closely it's paradigm is related to physical software design. This is such a fundamental difference to Doxygen (and others) that I don't think it should be brushed aside. Thanks, ErickR
|
|
|
|
|
It looks very well, but there is one thing I do not see:
In the "Call Graph" I do not get what I would expect:
Every Point in the app where that method is called from and every method it calls.VC has something like this but has serious problems when using objects from libraries.
The same goes for data members.
This is actually the most desired feature of any documenter.Anything else is nice, good to impress supervisors, but with very little practical use.
But maybe I have looked in the wrong place...
|
|
|
|
|
I think we know what you mean. Until now we're still using the original callgraphs from Doxygen, and they are a bit strange.
Seems that the arrow goes between classes, instead of between the individual methods in classes. We do plan to fix this . We are still rewriting all the graph generation code, to use a compiled-in version of the dot-tool. we have made an easy to use class based API for generating dot-graphs. As soon as we have that working in the old way we will look into the call-graph diagrams. Any suggestions to how it should work are welcome.
|
|
|
|
|
This may sound like a bit fo a noob question, but when I run doxys on some source I get a Windows pop-up "Open File - Security Warning" asking if I want to run dot.exe. The problem is it pops up about a thousand times while doxys is creating the documentation files.
I figure someone here would know how I can disable this bizarre behavior?
|
|
|
|
|
Do you have the file on a network or removable drive?
John
|
|
|
|
|
No, Doxys is installed on my main drive. I am running a RAID 1 (Mirror)configuration though.
|
|
|
|
|
I really like what this tool is doing for me. However, I've one problem I can't figure out. I'm documenting a typical function in the following manner:
/**
Enable or disable the window's menu.
EnableMenu enables or disables the window's menu and submenus.
*/
void cWindow::EnableMenu(HMENU _hMenu, ///< The menu to enable
bool _Enable) ///< #true# to enable
{
if (_hMenu==GetMenu())
SetMenu(_hMenu);
}
In the generated documentation, I get the parameter description repeated. The parameter list will be correct, but I will see "The menu to enable The menu to enable" in the description.
Any ideas what I'm doing wrong? Can I give you any more information?
|
|
|
|
|
Hi Doxy's
I haven't tried your tool yet, but the screenshots turned me on - so I want to know a bit more about the project and its future before i commit myself to using the tool.
What's the future plans of this project? I can see that there is a lot of things to do
http://www.doxys.dk/doxys_homepage/homepage/Project_Status/FeaturesTodo0_page_description.html
But how dedicated are you? Are you willing to commit to the future development that is needed to keep this project alive? Is this going to evolve into a commercial product at some time? What about donations?
One important issue is IDE integration - do you have any plans in that department? I've tried using a webbrowser on the side, but it's not the same as something that is integratet - like Eclipse and Javadoc.
Last but not least, its nice to see a project from DK here
/Markowitch
|
|
|
|
|
First: Thank you Well try it out. It's very easy to use. Just place yourself in the root of your code directory and type 'doxys'. Assuming you placed doxys and dot executebles somewhere in your path.
As for the commited thing:
We are very committed both of us and will continue to develop DoxyS. We have been working quite hard for 1½ years to get to where we are now, but we still have lots of ideas . Also we wish it to become as stable and reliable as possible!
IDE integration:
We do have some IDE integration for VS.NET, and Bobby Michalca has promised to make an even tighter form of integration to VS.NET (I'm not sure actually what this exactly mean though).
We plan to make tools to help you actually write the documentation via plugins for various editors. But if it's just about being able to access documentation from the IDE, we so far only have it for VS.NET. We would very much like to have it for other editors, but we would probably need some help from you people out there in order to do that
Maybe you can elaborate a little on what you mean when you say IDE integration or perhaps you can even help in implementing it .. either by doing it yourself or a least educate us howto make IDE integration for Eclipse if thats the one you want support for. Making the XML file for .NET integration was not that hard, and the class doing it should make a good stating point for others like it.
Regards The DoxyS team (Martin Harring & Martin Lütken)
|
|
|
|
|
Doxys can generate the Html Help projects for you. Also there are some settings to make doxys look more like MSDN (no menu on left side, etc).
After that all you have to do is call hhc to generate .chm file. More details on will be available with the next release help.
|
|
|
|
|
.
modified 17-May-14 11:59am.
|
|
|
|
|
Well thanks a lot
I don't think we quite understand what you mean ??? Ofcourse we have used DoxyS to generate our own documentation ... It is a documentation program after all!
Perhaps you refer to the HowtoDocument class/example, and perhaps you are right about that, but on the other hand other people have found it to be quite illustrative. We perhaps could also make a more normal approach with plain pages describing how to document code.
I suppose it's not the other pages like fx. this one:
http://www.doxys.dk/doxys_homepage/homepage/Documentation/Documenting/Documentingthecode0_page_description.html
that you don't find readable ???
Regards the DoxyS team (Martin Harring & Martin Lütken)
|
|
|
|
|
Thanks for a great tool! Very impressive.
In using doxys for C++ .NET code, the __gc specifier seems to confuse the way variables are identified. I get multiple variables all called __gc (but hiding their real name) in the output listing.
I built a filter to strip out 'whitespace __gc' then set up the doxys control file to pass the
input through that filter (wonderful feature!). This works in that all the variables are now properly listed in the output, but I have problems when using array specifiers. The variable is listed just as a scalar.
For example: int a __gc[];
is run through the filter, producing: int a[];
In the documentation, the variable is described as int a
with no mention that it is an array.
Is this correct or the way it's supposed to work?
-- Tom
|
|
|
|
|
Hi Tom
We are very happy that you like it
I was not familiar with the _gc specifier, but I've found out now what it does. But actually I don't think it has anything to with your problem. It seems to be general: Meaning that I think that a variable which is an array is not listet in the documentation as being an array, which of course is an error, and I'll put it on our todo list immidately!
Regards the DoxyS team! (Martin Harring and Martin Lütken)
|
|
|
|
|
Great tool = 5! Do you plan to add CHM (help file) generation support?
|
|
|
|
|
Thanks, we are very happy to hear that you like our work.
In the next release of DoxyS you will find support for chm files, thanks to Bobby Michalca.
Version 0.84b will be release around 20. march 2005
Kind regards
The DoxyS team (Martin Harring & Martin Lütken)
|
|
|
|
|
I have tried quite a few documentation tools and for the most part I have found that they take quite a bit of tweaking to get reasonable output. I installed doxyS and executed it from my projects source and without any tweaking I got my documentation. One of the things I like the most is that the documentation is in the one html page per member function. The integrated search and inheritance graphs are also very good and I did not have to do any work at all to get them.
Thank You for releasing this to GPL,
John
|
|
|
|
|
Hello,
After test in my big project (>2700 source files > 52 MB source code) I must say: VERY NICE AND GOOD. You get a rating of 5 from me. Nevertheless I have some hints or ideas, the make DoxyS better:
- In each directory you generate a file "arial.ttf". In my project is there a sum of 142 files with 43 MB. And I can not found any code snippet, that use this arial.ttf
- Have you think about the idea, to build a database with all informations and generate the website's dynamical instead of static html-files? In this case, I think, you can decrease the complete result set (>1GB !!! in my project), because you don't need all informations redundant. If you want, I can help you to design the database struct . Maybe this is also better to solve my next idea:
- I good an fast way to update all, if I have made some changes in source code. To generate all help files for my project I wait 1,5 hours !!! on a P4-3000 with 1GB RAM.
- Maybe it's a better solution, to put some javascript code in the HTML-files, to show some source code instead to put the source code in the html files direct. The javascript code can load the source direct from source file.
- I have seen, that you parse "normal and old web projects with javascript code". What's about web projects written in VB.NET? Here you have classes, methods and members too. Please support ASP.NET! This would be a nice feature.
Best regards
Stephan
|
|
|
|
|
Hi Stefan.
Thanks for the nice words about DoxyS.
The "arial.ttf":
Dot, the external program for making all the graphs, is using the font. For every directory we want to run dot in, we need the font file We are aware of the problem, and will fix it!
At the end of the documentation process DoxyS should remove all the fonts again.
The database:
It's a very good idea to put things in a database. It will save a whole lot of time when creating the documentation.
We would very much like your help to make the database.
Please write to doxys@doxys.dk so we can arrange something.
Reading the data from Javascript:
You are right, it takes up a lot of space!
All source files is parsed and made linkable form the c++ code. Therefore it will be very problematic/imposible to read it up as you click on the link.
To do this, it will requre some kind of user rights for the script to access the code files.
The code and the documentation will easily get out of synch.
DoxyS is made to easy to use. Unzip, generate and click on the link. That's the reason for making it in HTML, but an option for database output will be fantastic.
Please elaborate on the last part:
"- I have seen, that you parse "normal and old web projects with javascript code". What's about web projects written in VB.NET? Here you have classes, methods and members too. Please support ASP.NET! This would be a nice feature."
Kind regards
The DoxyS team (Martin Harring & Martin Lütken)
|
|
|
|
|
Hello DoxyS team!
In the last part I mean the following:
A part of my project is a website. The old version of this site is written for IIS-ASP with JavaScript for server- and client site code. Since last year I convert the webproject to ASP.NET with VB.NET on server site and JavaScript on client site.
I have seen, that doxys parse all the old website code and produce html documentation files. Now I think it's I good feature, that doxys can parse .NET-Webproject too. In my case, parse VB.NET classes with members, methods, constants and so on.
To my offer, to help you to design a database:
First I need detailed informations about your actual directory design. Which files with which name scheme you generate. Which informations exist in each file type and which informations in the files are redundatn in other files. You can contact me about stephan.pilz@stephan-pilz.de
If we create a database and a website, the result is, that a local webserver produce the output. In this case there is no problem to load a file from local hard disk into memory. This solves the problem with access rights in javascript. All things makes the local webserver. IIS is included in W2K, WXP, ...
Kind regards
Stephan
|
|
|
|
|
I tried it on a fairly large project (300K lines) and I got:
qgarray.cpp, line 387: out of memory error
My system has 768MB, and it took it all (peaked at 650mb) !!!
Also, does there really need to be so much command line output. Perhaps a HTML page for all the errors would be better.
|
|
|
|
|
Hi
About the command line output. We are planning to make HTML pages with warnings, errors, and all kinds of statistical information. And when we have done that we probably should add some more quiet run modes .. Good suggestion ..
About the out of memory problem, we would vere much like to be able to recreate it. Is your code proprietary or is it possible for us to have a copy of it so we can get the bug fixed ?
Anyway you can email me at ml@doxys.dk
Regards Martin Lütken
|
|
|
|
|
Have you tried to change virtual memory settings (if you're using Windows).
It should be possible to get up to 3 GB og virtual memory! It might help.
Of course we will at some point look deeper into DoxyS's memory consumption
Regards DoxyS team
|
|
|
|