Hi all, (cc. Inkscape devel, maybe there are some documentation wizzards out there)
I've started a bit of documentation work. The Doxyfile configuration file for doxygen has been updated to the latest version. I've also made some tweaks that I found useful, or want to try a bit. First hour I am using doxygen so...
Go to lib2geom's root and run doxygen. Then, you should get doc/html/index.html, which is the homepage of the generated documentation. As you can see, there is a lot to do.
Please read a bit of the doxygen manual if you want to contribute a lot.
Note 1: Doxygen can generate nice equations: http://www.stack.nl/~dimitri/doxygen/formulas.html Put your LaTeX equations between a pair of "\f$" commands: \f$ x = 1 \f$
Note 2: Doxygen makes use of special commands you can put in your code, such as: /** \brief Scales this vector to make it a unit vector (within rounding error). * * The current version tries to handle infinite coordinates gracefully, * but it's not clear that any callers need that. * * \pre \f$this \neq (0, 0)\f$ * \pre Neither component is NaN. * \post \f$-\epsilon<\left|this\right|-1<\epsilon\f$ */ void Point::normalize() { ...
It is worth checking out other commands like \param, \see and \return.
Note 3: The documentation is filled with "Geom::" namespace. I have not yet figured out how to tell doxygen to only document the Geom:: namespace and leave all other things (like std!!!!?!??!) out.
Note 4: Doxygen accepts two command styles: \pre and @pre. They can be mingled without a problem I think, but shall we try to use the slash? \file, \brief, etc.
Note 5: I'll be adding a lot of empty template documentation comments, so you don't have to think much about how to add documentation. This way, many people can help without much knowledge of doxygen.
Note 6: We should get a server to run this every day and put it on the web somewhere! (including a tar so people can download it?)
Cheers, Johan
J.B.C.Engelen@...1578... wrote:
Hi all, (cc. Inkscape devel, maybe there are some documentation wizzards out there)
I've started a bit of documentation work. The Doxyfile configuration file for doxygen has been updated to the latest version. I've also made some tweaks that I found useful, or want to try a bit. First hour I am using doxygen so...
MySQL is had also started a project about doxygen-ating their comments.
They have some info at http://forge.mysql.com/wiki/CommunityDoxygenProject . I hope you find something useful in there.
Regards Vangelis __________________________________________________ �������������� Yahoo!; ���������� �� ���������� �������� (spam); �� Yahoo! Mail �������� ��� �������� ������ ��������� ���� ��� ����������� ��������� http://mail.yahoo.gr
On Oct 1, 2008, at 3:41 PM, J.B.C.Engelen@...1578... wrote:
Note 4: Doxygen accepts two command styles: \pre and @pre. They can be mingled without a problem I think, but shall we try to use the slash? \file, \brief, etc.
The main point of the "@" format is to be compatible with JavaDoc, which was the main thing to push such doc comments.
One factor for using the "@" form is to allow for different tools to be used in addition to Doxygen.
Another factor is to allow developers working on Java code to use a consistent format across source file types.
-----Original Message----- From: Jon A. Cruz [mailto:jon@...18...] Sent: donderdag 2 oktober 2008 10:24 To: Engelen, J.B.C. (Johan) Cc: inkscape-devel@lists.sourceforge.net; lib2geom-devel@lists.sourceforge.net Subject: Re: [Lib2geom-devel] [Inkscape-devel] documentation effort
On Oct 1, 2008, at 3:41 PM, J.B.C.Engelen@...1578... wrote:
Note 4: Doxygen accepts two command styles: \pre and @pre. They can be
mingled without a problem I think, but shall we try to use the slash?
\file, \brief, etc.
The main point of the "@" format is to be compatible with JavaDoc, which was the main thing to push such doc comments.
One factor for using the "@" form is to allow for different tools to be used in addition to Doxygen.
Another factor is to allow developers working on Java code to use a consistent format across source file types.
The main reason I proposed to use slashes is because I have not found use of @ for doxygen commands. (2geom already has a quite some doxygen text). So conversion to use the @ would be quite a bit of work.
MySQL insists on using '@' but does not give a reason (and I can't find one in doxygen's manual).
One factor for using the "@" form is to allow for different tools to be used in addition to Doxygen.
Do you mean tools for adding comments in doxygen format?
I am undecided on this one, just that '' saves us from converting stuff and is what current 2geom coders have been doing.
Johan
I have always preferred @ myself, just because it is more universal. Also, it looks similar to the xpath @ for 'attribute'.
I really see no reason for people to change from what they are already using. Not altering anyone's style preference has always been a rule with me. A parser or regexp can be written to handle either.
bob
On 10/5/2008 10:00 AM, J.B.C.Engelen@...1578... wrote:
-----Original Message----- From: Jon A. Cruz [mailto:jon@...18...] Sent: donderdag 2 oktober 2008 10:24 To: Engelen, J.B.C. (Johan) Cc: inkscape-devel@lists.sourceforge.net; lib2geom-devel@lists.sourceforge.net Subject: Re: [Lib2geom-devel] [Inkscape-devel] documentation effort
On Oct 1, 2008, at 3:41 PM, J.B.C.Engelen@...1578... wrote:
Note 4: Doxygen accepts two command styles: \pre and @pre. They can be
mingled without a problem I think, but shall we try to use the slash?
\file, \brief, etc.
The main point of the "@" format is to be compatible with JavaDoc, which was the main thing to push such doc comments.
One factor for using the "@" form is to allow for different tools to be used in addition to Doxygen.
Another factor is to allow developers working on Java code to use a consistent format across source file types.
The main reason I proposed to use slashes is because I have not found use of @ for doxygen commands. (2geom already has a quite some doxygen text). So conversion to use the @ would be quite a bit of work.
MySQL insists on using '@' but does not give a reason (and I can't find one in doxygen's manual).
One factor for using the "@" form is to allow for different tools to be used in addition to Doxygen.
Do you mean tools for adding comments in doxygen format?
I am undecided on this one, just that '' saves us from converting stuff and is what current 2geom coders have been doing.
Johan
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK& win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Regarding the documentation effort (not specifically 2geom) - I have recently checked in some XML tree documentation, including the observer and (deprecated) listener API. I hope it will be useful. However, there are a few widespread problems with the doxygen docs in Inkscape:
1. Malformed file comments. There are 2 compound problems: forgetting @file, so the comment doesn't document the file but the first thing in it (usually the Inkscape namespace - see the docs to witness how pervasive this mistake is), and putting legal / credits stuff in the doxygen comments. I think it doesn't belong in the documentation. Here is a template that corrects both errors:
/** @file * @brief Brief description of what this file contains * * Some more detailed description if you wish. */ /* Authors: * Some author * * (C) 2008 Authors * Released under GNU GPL, see file 'COPYING' for details */
#ifndef INCLUDE_GUARD #define INCLUDE_GUARD
... rest of file ...
2. Class descriptions in file comments. Obviously it's better to put class descriptions in class comments. 3. Skimpy descriptions of important things. Generally it's better to be overly verbose than to miss crucial details. The most important thing missing documentation right now is probably the GC system. 4. Unnecessary jargon. At first I had trouble understanding what "repr" is. The full word "representation" almost never appears. 5. A minor but related problem: newlines after Vim modeline, which break its function. 6. No attribution or legal notice in the file.
Fortunately most of those problems are easy to fix.
J.B.C.Engelen wrote:
Note 4: Doxygen accepts two command styles: \pre and @pre. They can be mingled without a problem I think, but shall we try to use the slash? \file, \brief, etc.
I like @ more, because it's visually more distinct - it's just easier to spot doxycomments when they use @ rather than . However, which one we use is really irrelevant - writing more documentation is more important than debating about details.
There is one more to think about - where do we put the documentation? Do we put it in the header files like every library I have seen to date, or in the .cpp files where the functions are defined?
-----Original Message----- From: Krzysztof Kosiński [mailto:tweenk.pl@...400...] Sent: donderdag 16 oktober 2008 3:06 To: inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] documentation effort
There is one more to think about - where do we put the documentation? Do we put it in the header files like every library I have seen to date, or in the .cpp files where the functions are defined?
Preferrably in the cpp files, since this reduces recompilation times by a lot.
On Oct 16, 2008, at 2:48 AM, J.B.C.Engelen@...1578... wrote:
-----Original Message----- From: Krzysztof Kosiński [mailto:tweenk.pl@...400...] Sent: donderdag 16 oktober 2008 3:06 To: inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] documentation effort
There is one more to think about - where do we put the documentation? Do we put it in the header files like every library I have seen to date, or in the .cpp files where the functions are defined?
Preferrably in the cpp files, since this reduces recompilation times by a lot.
I disagree.
The .h files are supposed to be the public interface for a class or code. Also once an API is created, it should change very rarely, as opposed to the implementation which is in .cpp files and is expected to change often. And given that documentation doesn't change nearly as much as implementation, one shouldn't see frequent compiles triggered by doc changes. For files that might be included by many others (and thus be prone to triggering long recompilations) the fact that they are included by many other files would indicate they are core classes that many other things depend on and thus should see their API change even less frequently that others.
It also helps developers in day-to-day use. One only has to open a .h file to see the complete documentation for a class, with all methods documented one after another. If the documentation is placed in the .cpp file one would have to look in one file to see what a method is, then open a second much larger file and search throughout to finally find the implementation with the docs attached.
(A minor follow up to reduce compile times is to reduce the number of .h files being included and to avoid having .h files include other .h files)
-----Original Message----- From: Jon A. Cruz [mailto:jon@...18...] Sent: donderdag 16 oktober 2008 18:41 To: Engelen, J.B.C. (Johan) Cc: tweenk.pl@...400...; inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] documentation effort
On Oct 16, 2008, at 2:48 AM, J.B.C.Engelen@...1578... wrote:
-----Original Message----- From: Krzysztof Kosiński [mailto:tweenk.pl@...400...] Sent: donderdag 16 oktober 2008 3:06 To: inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] documentation effort
There is one more to think about - where do we put the
documentation?
Do we put it in the header files like every library I have seen to date, or in the .cpp files where the functions are defined?
Preferrably in the cpp files, since this reduces
recompilation times
by a lot.
I disagree.
The .h files are supposed to be the public interface for a class or code. Also once an API is created, it should change very rarely, as opposed to the implementation which is in .cpp files and is expected to change often. And given that documentation doesn't change nearly as much as implementation, one shouldn't see frequent compiles triggered by doc changes.
Personally, I don't care too much about compile time; but many people do, judging from past emails on the list after just a couple commits that changed e.g. verbs.h. If we start working on documentation, we can expect many small commits (e.g. just a typo fix).
For files that might be included by many others (and thus be prone to triggering long recompilations) the fact that they are included by many other files would indicate they are core classes that many other things depend on and thus should see their API change even less frequently that others.
This does not mean their documentation isn't changed frequently.
It also helps developers in day-to-day use. One only has to open a .h file to see the complete documentation for a class, with all methods documented one after another. If the documentation is placed in the .cpp file one would have to look in one file to see what a method is, then open a second much larger file and search throughout to finally find the implementation with the docs attached.
I myself find browsing through a header file with documentation very annoying. I like to look at a header file and see all methods etc at a glance. With lengthy documentation in it, it can be much harder for example to see whether a particular method is private or public. Without documentation you can quickly find which methods exist, check the exact spelling of some function or the exact order of parameters. Otoh, it is cumbersome to add documentation about a member variable in the cpp file. I guess it depends on why one looks in a header file; I almost exclusively look there to see which functions there are and what the spelling was or the param order. So, maybe a good compromise would be to add documentation about methods in the cpp file, and documentation about members in the header file. Documentation about methods can be lengthy and can contain many details, documentation about members is usually much smaller; so the header file won't be so bloated.
I guess for libraries, the documentation almost has to be put in header files, as the user only has those available (and the cpp files compiled to binaries). Something that's important to think about for lib2geom.
In any case, I started the documentation thread because of 2geom. I don't think there will be a big documentation effort on Inkscape. (Hope I didn't put anybody off with this comment, of course all documentation is very much appreciated!)
Cheers, Johan
J.B.C.Engelen wrote:
Personally, I don't care too much about compile time; but many people do, judging from past emails on the list after just a couple commits that changed e.g. verbs.h. If we start working on documentation, we can expect many small commits (e.g. just a typo fix).
For files that might be included by many others (and thus be prone to triggering long recompilations) the fact that they are included by many other files would indicate they are core classes that many other things depend on and thus should see their API change even less frequently that others.
This does not mean their documentation isn't changed frequently.
Actually, I think putting docs in headers would force people to make decent docs the first time they write them, because each change will trigger a rebuild of a large part of Inkscape. Right now they usually make skimpy documentation with the intent to expand it later, but in the end it never happens. It will also encourage people to document more at once - if they know a documentation change will trigger a rebuild, they will be more inclined to ensure it's worthwhile.
Another consideration is that for virtual base classes like XML::Node you have to put docs in the headers anyway, or in a completely separate file, but that defeats the purpose of Doxygen.
J.B.C.Engelen wrote:
I myself find browsing through a header file with documentation very annoying. I like to look at a header file and see all methods etc at a glance. With lengthy documentation in it, it can be much harder for example to see whether a particular method is private or public.
The solution is to look at the generated docs instead. Additionally Doxygen can generate an annotated source so you can read the header without all the doxycomment clutter if you wish. I find that using Firefox to page through Doxygen docs created with EXTRACT_ALL and cross-references along with a regular text editor can be a fairly decent substitute for an IDE. But that may be just me :).
Regards, Krzysztof Kosiński
participants (5)
-
unknown＠example.com -
Bob Jamison -
Jon A. Cruz -
Krzysztof Kosiński -
Vangelis Katsikaros