Let's Use Doxygen

[Entropy]

Doxygen is a nice document generator, and we can use it to document the source code and stuff. What do you guys think?

[Leeloo]

Sounds like the stuff some people are trying to get us to use here at work... Putting a lot of documentation inside the source files, so the piece of code you're looking for gets even harder to find.

 

Maybe it can be used in a good way, but I've only seen tools like that used in bad ways.

[Wytter]

Well, perhaps it would give us better chances of getting developers to EL that the project has better documentation. It can take a long while to dig through 47k lines, especially when the majority is not documented in other ways than the function/variable name.

[Leeloo]

It will take even longer to dig through 150k lines, even if 2/3rds of them are specially formatted comments.

[Wytter]

Hmm, true... What do you suggest then? That we make a basic overview of the program flow? Could be done in a few pages...

[Leeloo]

To be honest, documenting code has never been my strong side. "What do you mean I need to comment it, it clearly says if x > y, if a programmer can't understand that, you hired the wrong guy". And then three months later "why the heck when x is greater than y?".

 

So, don't expect any absolute truths about documentation from my side, only comments and opinions

[Guest Dagyde]

Well, perhaps it would give us better chances of getting developers to EL that the project has better documentation. It can take a long while to dig through 47k lines, especially when the majority is not documented in other ways than the function/variable name.

Can developers' projects currently read existing map files shipped with the EL client?

 

Besides earlier advice to "use a packet sniffer" to discover the API, how would you suggest would-be EL-hackers/developers learn about how to communicate with the server? WHat documentation has the EL team provided for people that want to help?

 

What restrictions are in place to cause programmers to be afraid to help?

 

I think several changes are required before you have people jumping in to help in a big way. Doxy is a good start.

[Wytter]

I agree... We should provide much more documentation about the client, and I will work on that for the next 2 weeks - after that I have to leave and go to the military, sadly (conscription) hence EL will actually only have 1 active developer left (Mihai).

 

I'll do what I can to ensure that more people will get willing to help us out.

 

About network data - this area is more important to bot makers than to EL developers. The data is already parsed properly, and we just need to extend the protocol if necissary. But of course this will be handled.

 

I think we should use the wiki on berlios for this... Doxygen is a good way of doing it as well, but as Leeloo pointed out, it might mean unnecissarially clogging the source with documentation.

[Entropy]

Umm, what I meant was to generate EXTERNAL documentation, in html files, and post them on the web. Not comment the code in the code, we can do that with any text editor.

[Malaclypse]

But doxygen is a tool to extract documentation from within source files into html files. You decorate the headers of functions and datatypes for this, no comments within the actual code beside the ones that already exist (if any).

 

If you wan't to generate external documentation from scratch you won't need a tool like doxygen at all. But maybe using docbook would be a good choice then.

 

Putting a lot of documentation inside the source files, so the piece of code you're looking for gets even harder to find.

Why don't you use the folding capabilities of your favourite editor to hide them

[Entropy]

Hmm, from what I read it can be used in many ways:

It can help you in three ways:

 

  1. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in $\mbox{\LaTeX}$) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.

  2. You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.

  3. You can even `abuse' doxygen for creating normal documentation (as I did for this manual).

[Wytter]

Here's an example (ran it quickly without really doing that much configuration, and it also has some documentation on a feature that isn't in CVS yet - displaying books ;-)):

 

http://wytter.tfm.ro/elc/doxygen/html/main.html

[Malaclypse]

2. You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.

 

I wasn't aware of this. But the result are nice. I think this could be a starting point to manually write some documentation.

[Malaclypse]

To be honest, documenting code has never been my strong side. "What do you mean I need to comment it, it clearly says if x > y, if a programmer can't understand that, you hired the wrong guy". And then three months later "why the heck when x is greater than y?".

 

So, don't expect any absolute truths about documentation from my side, only comments and opinions

 

I don't think that a documentation of such an example might even be useful.

 

But do you remember all the asumptions, all the pre- and post-conditions that were met when you wrote the code, if you look at it after several months, or if it's the first time you take a look at the code? Can you interpret the precise semantics of what you read in the source code always in the intended way? C has multiple points of how to interpret several language constructs, to clarify the particular meaning in several places is a good thing to anybody else who might want to read that code or might get incorporated in the coding process and thus has the need of a deeper unterstanding of the code. I found, that documentation can help a lot here, although I'm aware that there are other points to this as well.

[teranoz]

Huh ? you need another program to see classes ??

Is that not in the holy freeware compiler ?

[crusadingknight]

Huh ? you need another program to see classes ??

Is that not in the holy freeware compiler ?

Lol, in gcc? ROFL. (Dev-Cpp has it, but you can't parse a menu, nor search it, can you?)

[Wytter]

Okay, we decided to use doxygen to document the header files - that should be sufficient, and won't clog the .c-source files :-)

 

EDIT: nvm, figured it out ;-)

Edited January 14, 2005 by Wytter

[Wytter]

OK, I began documenting. Have a look in the CVS - Currently it only has [23]d_objects.h documented and only a few groups, but more will be added as we go :-)

 

In linux:

 

make -f Makefile.linux docs

 

Will create documentation from the Doxyfile in ./docs/ and save to ./docs/html/...

 

For everyone else:

 

http://wytter.tfm.ro/elc/docs/html/index.html

Edited January 15, 2005 by Wytter

[Wytter]

Just updated the doxyfile in CVS.

 

Mihai... Would you please do a make docs and post a link to it? Takes forever to upload all the graphs.

[Wytter]

OK, started doing this in a more ordered way.

 

The pure doxy-files such as group definitions will have the .doxy extension. Currently 2 files have this:

 

main.doxy - The main page

groups.doxy - Containing the group definitions

 

Currently the Doxyfile in ./docs/ generates callgraphs for all functions. We will later on change this so it'll only generate it for some functions.

 

Currently I've ~finished documenting:

2d_objects.h

3d_objects.h

actors.h

actor_scripts.h

 

If you have any comments to the structure or the documentation I've made please tell me :-)

[Wytter]

A small update:

 

Documentation has been written for:

 

2d_objects.h

3d_objects.h

actors.h

actor_scripts.h

asc.h

books.h

textures.h

tiles.h

timers.h

trade.h

translate.h

weather.h

widgets.h

[kl4Uz]

the problem is not the documentation. the problem is, that this game isn't released under the GNU GPL. Why should anyone put effort into it, if others are gonna get cash for it and the one who put effort in it, will become a second class player anyways if he doesn't pay the fee?

[Wytter]

First of all - there aren't that many developers, and there isn't that much money involved - some of it goes to Roja/Entropy who have worked on this game for over 2½ years and the rest goes to developers in terms of donations. Developers does not have to pay for extra "p2p" features - they are distinguished from "the rest" in that way. If you got to know them you might find that Roja and Entropy aren't money-hungry bastards ;-)

 

The reason why the license is somewhat restrictive is to send a signal saying that having your own illegal clients with i.e. automation enabled is unwanted (and illegal). In an mmorpg it is very hard to create systems that prevent cheating, and the task is not easier in an open source mmorpg.

 

The bottom line is that you will benefit from helping; you will get a better game, and you will get certain privileges that other players do not have - and from time to time also donations, but it's not like we're in this for the money ;-)

 

I know that documentation will help some of the people who wish to help with the client, but haven't gotten about reading through the >50k lines... If you do not wish to help since the game is not GPL - well, that's too bad, but fortunately not all developers are like that.

[Dingar]

Oh quit being a hippie for a moment and be a geek. Being able to see the source means you can say "Damnit, I'm going to write a patch to have a user setting to disable y-axis view rotation with the mouse," if you happen to dislike said feature, rather than just having to be annoyed and harp at the devs who have plenty to do already.

 

I've been a GPL fan since Linus released the linux kernel under it but it doesn't have to be on every piece of software. The real reason geeks write code isn't for the Betterment Of The Community or for Fat Wads Of Cash. We code because we have to.

 

Every geek has a primal desire to solve problems that can't be fought. In the end, it's not the credit, cash, or warm, fuzzy feeling of socialism actually working that drives us. It's the challenge.

 

So, if you feel the need to get on some quasi-religious GPL zealotry kick, do it on usenet where it belongs.

 

Edit: Just so this isn't an entirely off-topic post, I offer the following. I'll stick with grep, vi, and reading the code if it's all the same to you folks, but it's not a bad idea.

 

EOF

Edited January 21, 2005 by Dingar

[Placid]

Oh quit being a hippie for a moment and be a geek.  Being able to see the source means you can say "Damnit, I'm going to write a patch to have a user setting to disable y-axis view rotation with the mouse," if you happen to dislike said feature, rather than just having to be annoyed and harp at the devs who have plenty to do already.

 

I've been a GPL fan since Linus released the linux kernel under it but it doesn't have to be on every piece of software.  The real reason geeks write code isn't for the Betterment Of The Community or for Fat Wads Of Cash.  We code because we have to.

 

Every geek has a primal desire to solve problems that can't be fought.  In the end, it's not the credit, cash, or warm, fuzzy feeling of socialism actually working that drives us.  It's the challenge.

 

So, if you feel the need to get on some quasi-religious GPL zealotry kick, do it on usenet where it belongs.

Amen.

Edited January 21, 2005 by Placid