Doxygen all the things!

Discussions About CyanWorlds.com Engine Client & Plugin
User avatar
Luna
Member
Posts: 11
Joined: Sat Apr 09, 2011 2:37 pm

Doxygen all the things!

Post by Luna »

Hi all

I have noticed there are several people interested in documenting the code in a Doxygen fashion and as I am interested myself, I decided to make a topic on this, I hope I am not being too presumptuous :/ I just felt that it might be useful to have a topic dedicated to the discussion of where to start implementing Doxygen(which repo) and possible problems that people have while they are documenting(uncertainty what something does, or whether it is ever used).

I saw a discussion on the repository in #writers, where they suggested that the bitbucket repository is used as both OU and H'Uru can easily merge from here. (Please correct me if I understood this wrong). I was wondering what the people here at OpenUru.org think of this?
User avatar
Mac_Fife
Member
Posts: 1239
Joined: Fri Dec 19, 2008 12:38 am
Location: Scotland
Contact:

Re: Doxygen all the things!

Post by Mac_Fife »

Not presumptious at all. We made a comment right at the start of CWE to say that there were sign's that Doxygen had been in use at some point in Cyan's code development so we'd like to see that developed: http://wiki.openuru.org/index.php?title ... umentation

The Bitbucket repo gets synchronised with the OU Foundry repo every 6 hours (I think) so that's good for us. I'm not sure if H'uru pull from Bitbucket or directly from the Foundry, but that's probably irrelevant since both repos will track each other.
Mac_Fife
OpenUru.org wiki wrangler
Jons
Member
Posts: 11
Joined: Sun Jan 29, 2012 1:48 pm

Re: Doxygen all the things!

Post by Jons »

Bonjour,

What a coincidence! I was just wondering about that yesterday. Many programmers seem to like Doxygen. If a repository where both main CWE banch can pull the doc, it would be ideal. As I'm not familiar about all that repository synchronization thing, I will stay tuned to know what is discussed here to be ready if I jump in that kind of documentation.

Good idea Luna! :)
Jons
User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Relationship GoW - OpenUru.org

Post by Lyrositor »

Quick question: what would be a good starting point for documentation? I'm thinking of starting with plUruLauncher, then progressively working outward and upward, before going back down once I've reached the top. I've generated a Doxygen report for Plasma, and it's PRETTY BIG, to say the least... Or, I could give a brief description of each file and then move on.
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image
User avatar
rarified
Member
Posts: 1061
Joined: Tue Dec 16, 2008 10:48 pm
Location: Colorado, US

Re: Relationship GoW - OpenUru.org

Post by rarified »

I'd work from the inside out.

Pick what appear to be some fundamental data structures. Form a hypothetical description about what they contain, and assertions about the values and relationships. Then explore how the data structure is used (follow the Doxy graphs) and refine your description.

Keep it simple to start. Geometric coordinates. Events. That sort of thing. Then you build a foundation to describe increasingly complex items.

My approach to refining the generation of Doxygen is to start clustering the reports in the functional subsystems as the directory hierarchy indicates. Network communications. Graphics. Only generate a report for that subsystem to make it more readable. That's on my todo list. But I havn't even begun to contemplate adding the Doxy descriptions to the code, which is where you are.

_R
One of the OpenUru toolsmiths... a bookbinder.
User avatar
Luna
Member
Posts: 11
Joined: Sat Apr 09, 2011 2:37 pm

Re: Relationship GoW - OpenUru.org

Post by Luna »

@Lyrositor : As doxygen doesn't really have anything to do with the relationship between GoW&OU maybe we should discuss it here : viewtopic.php?f=92&t=735? That way it is all in one topic and not across the whole forum >.>
User avatar
JWPlatt
Member
Posts: 1137
Joined: Sun Dec 07, 2008 7:32 pm
Location: Everywhere, all at once

Re: Doxygen all the things!

Post by JWPlatt »

Fished your wish!

Posts split from OU/GoW discussion and merged here.
Perfect speed is being there.
User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Doxygen all the things!

Post by Lyrositor »

If I'm correct, the following directories have the following functions :
- Apps: code for all the executables to be distributed,
- CoreLib: basic stuff (math, vectors, debugging); maybe I should start here?
- CoreLibExe: handles logging memory leaks, errors, printing error messages...
- FeatureLib: various essential game aspects (camera handling, KI, localization...),
- NucleusLib: don't know. Seems to be a lot of network stuff, though. Is this the platform-dependant code?
- PubUtilLib: again, not sure. Seems to be a lot of stuff. Dependencies?
- PythonLib: Python interfaces.
Is Pch.h a part of the patcher program? It keeps cropping up...
I think that once I know how everything is globally laid out, I should be ready to delve into the code and document. I'm just trying to get my bearings in this huge project.
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image
User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Doxygen all the things!

Post by Lyrositor »

I pushed my first attempt at documentation.
Changed files:
https://bitbucket.org/Lyrositor/cwe-ou/ ... HeadSpin.h
https://bitbucket.org/Lyrositor/cwe-ou/ ... adSpin.cpp
A bit confused, so I kept it simple. :?
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image
Jons
Member
Posts: 11
Joined: Sun Jan 29, 2012 1:48 pm

Re: Doxygen all the things!

Post by Jons »

Bonjour,

I have been told to start with plDispatch but I didn't tryed. I'm stubborn so I tend to continue my way until I fail. I'm working from UruLauncher and follow the logical steps (patch, login, avatar mangagement, join an age, etc...)

For now, I won't contribute directly in Doxygen doc before I finish the Use Case Scenario (or fail to do) so I can have a good idea how all things works. PlUruLauncher and PlClientPatcher are already done viewtopic.php?f=91&t=710&p=5911&sid=b9f ... ef94#p5903 .

I think pch.h are for pre-compiled header (you may be most familiar with stdafx.h) but did not verified that myself. If I'm not mistaken, they used it almost everywhere to lessen the compilation time required.

Hope it helps
Jons
Post Reply

Return to “CyanWorlds.com Engine - Client & Plugin”