Doxygen for Compiz-source?

[RYX]

Hi everybody! I've just had my first experience with doxygen and I really like it. I fully documentend my self-written painting program (written in ActionScript2, commented in javadoc-style) in about 10 minutes without further knowledge of doxygen (and without doxygen officially supporting Actionscript). So it came to my mind that it would be incredibly cool to have a doxygen-generated documentation for compiz. Of course - it would require commenting the whole sources, but a complete API-reference for compiz is worth the work.

I could do some commenting on most parts of the sourcecode but I think it would really make sense to involve David into this ... If we can comment the existing code, maybe he is willing to keep the comments up-to-date for further releases. (It would be only comments for functions, structures and maybe some important globals)

So - Is anyone interested in making this a task for the early next year? Or are there better choices than doxgen?

:)

[mikedee]

I think doxygen seems like a well liked solution, I do not have any experience of it myself though.

The problem I always find with doxygenated docs is that they lack a lot of information and examples. PHP has by far the best documentation of any language I have seen or used, the problem is it is all seperatly written so requires a large effort to maintain.

Examples and feedback are important but we probably do not have the resources to support it at the moment. I will try to group together some small real world examples which maybe could be linked with the doxygen docs to start with.

The commenting of source code is probably best attacked a file at a time, starting with the easy ones. Hopefully David can vet and possibly add his intentions to the docs. I am sure he is up for documentation but as most developers know it takes the most time and effort to maintain properly.

I am interested in helping, do you have any good links for doxygen tutorials (yes I am too lazy to google it :))

[fab]

I think it is a great idea too.

It would be a good way to start coding with compiz as it sometimes is a bit complicated to understand all of its internals ( even if the coding convention makes it pretty easy to understand ! )

I'd like to help out but i don't really have a lot of time available right now. Maybe later when all the projects i have to code for school are over !

[RYX]

I am unaware of how and where the comments have to be added for C-code, but maybe it is enough (and acceptable in sense of coding-style) to do it for compiz.h.

Honestly, PHP's documentation is nearly perfect, but doxygen is really easy and flexible and supports many output backends (Html, Latex, PDF, ...), so it should be possible to get the output into any form we want. Although I agree that comments and samples are quite essential, I'd say that a core-api reference is a good thing to have.

And here is the official "Getting started..." (http://www.stack.nl/~dimitri/doxygen/starting.html) ... (skip the graphics and start with "Step 1") :D

:)

[mikedee]

I am not arguing against doxygen, I am more thinking out loud about what we would need in documentation. Do you know if it is possible to have the html that is outputted include user comments?

I was looking for a quick ref to all the possible @tags, its not important for now, but if you see one on your travels you could post it here so that people can quickly start documenting. The doxygen website seems more geared up to producing the docs rather than writing them, but like I said its not too important at the moment.

I had a quick look at the dbus code since I have a copy here and they use doxygen. They (surprise surprise) do not have too much documentation at the moment. The structs seem to have each member documented in the .h file but the functions are documented in the c file. Dont know if thats standard, probably makes it easier to link to the file in question if we document the c file. I dont know how extensible doxygen is, so I am not sure if it can link to the actual c file.

[RYX]

Some interesting things I found out about doxygen:
- has its own included C-preprocessor
- doesn't need any comments at all (can simply dump the function names, vars, structures)
- allows html-tags within doc-comments
- can generate calling-graphs, inheritance-graphs (and some more I forgot)
- html-output can be customized via CSS and custom header/footer
- is even better for OOP-languages


How to use it (the javadoc-style) - sorry for not giving you a C-example, but I am coding too much AS atm:
/**
* This is a brief description.
* This is a longer description with more than one sentence.
*/
class Example
{
/**
* Example-Constructor.
* Create a new Example-object.
* @param var This is a sample variable.
* @return - Constructor returns nothing.
*/
function Example (var:String) {
// some code ...
}

/**
* A test-function.
* This function returns the number 5.
* @returns the number 5
*/
function test () : Number {
return 5;
}

}
So in javadoc-style, the most important @tags are @param and @return, but doxygen offers some other kind of documenting-tags.

:)

[PaK]

- doesn't need any comments at all (can simply dump the function names, vars, structures)

Maybe we could consider another solution that would give here more flexability. But offcours it would need more effort :)

1. doxygen or any c-parser -> xml data should dump function names, vars, structures
2. web interface would give use possibility to synchronize all data dumped from source with that data what is well documented and even commented by other users by that web interface.

This would give use php-like documentation for source, and possibility of easy synchronizing new source with documentation that already exists

[RYX]

Yes, I was only giving some facts. Of course - we should add comments to the documentation :D ...

Doxygen supports various output-backends (also XML) which we can use to make the data available for other purposes (like web-based reference).

:)

[mikedee]

Doxygen supports various output-backends (also XML) which we can use to make the data available for other purposes (like web-based reference).

My thoughts exactly! :)