Raydium 3D Game Engine

Official forum for everything about Raydium, ManiaDrive, MeMak, ...
It is currently Thu Mar 28, 2024 10:04 am

All times are UTC




Post new topic Reply to topic  [ 12 posts ] 
Author Message
 Post subject: Doc weekend
PostPosted: Tue Aug 04, 2009 10:54 pm 
Offline
User avatar

Joined: Thu Sep 29, 2005 2:59 pm
Posts: 828
This weekend (August 8th and 9th) a few people and myself are going to meeting in the #raydium channel in the freenode IRC server. Our goal is to convert all current format doc into doxygen format.
It's more or less compatible so the changes will be minor.
The idea has been welcome by the irc members (Xfennec is never there, so we have not yet his opinion 8. Xfennec, What do you think?) ).

The workflow will be simple. As soon as someone enter in the chat and ask for help us we will assign him/her a file for converting. Also we have a simple text file with guidelines about conversion rules.

If we complete the full task before the Monday we will be able to do a commit with the new(reformated) doc.

Advantages of doxygen: an extended documentation format, well supported, allow generating HTML, XML, PDF, Latex..., one page per function/chapter, can be easily generated from local sources and more.

If everything goes right, then maybe we could repeat the weekend for a real update of the documentation.


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Wed Aug 05, 2009 11:41 am 
Offline
User avatar

Joined: Sun Mar 16, 2003 2:53 am
Posts: 2591
Location: gnniiiii (Scrat)
First, I don't think IRC is the right place for tking decisions about the engine itself, for reasons I've already explained: need to here at the right place in the right time, no log, no search, no way to deeply think about what's said.
It's very odd to discuss of such a important choice with a few members on IRC and then post a message here saying "hey, to all that were not on IRC, we've taken this decision, we'll do this".

About Doxygen, I don't see the point. The current documentation system is very easy to extend (a very simple format, with a simple parser) to get most features you're talking about. The current parser was just a quick sample wrote in a few hours and made his job since. Imagine then what's possible with some little effort.

On the other hand, Doxygen format (in source code, I mean) is quite heavy, as the generated doc. I've worked with many projects using Doxygen as a default (most projects at work, in facts), and the result was simple: nobody was able to correctly browse the doc (except people who wrote the code) lost in a maze of useless classes, modules and forest of arrows. Certainly not user friendly, for sure. And that was in Object Oriented projects, were Doxygen is supposed to be best suited.

Of course, if some samples were produced during your IRC chat, showing that syntax could stay simple and resulting documentation could stay easy to use, I would be very pleased to see I'm wrong completely wrong about Doxygen, but since IRC is volatile, the only thing I see here is a very dangerous upcoming commit ...


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Fri Aug 07, 2009 4:45 pm 
Offline
User avatar

Joined: Thu Sep 29, 2005 2:59 pm
Posts: 828
Hi

Well, first an explanation about the IRC. We have no decided a thing about Raydium, we just decided to do a conversion (on our own) of the doc to Doxygen format. But this wasn't even a serious debate, I just propose it and people agree. Is not a decision about Raydium.
Also, making a commit of the result to raydium, if we finish it, is not a must. As said in the previous message "we will be able to do a commit". So it's just an option.
About chat IRC problem of log. It can be easily solved using a bot logger.

Now the big matter. Leaving doxygen apart, current doc system, sorry, is not good. Objectively is limited to 40chars per line, the format is not shared in other apps, for tweaking it you need php installed+knowledge about parsing+knowledge about destination format+php coding skills, the unique default output is a non-standard wiki format that can not use with other wiki-applications. Maybe i'm wrong but that's looks like a bad doc system for me.

Now return to Doxygen. Right now looks like the internal format of the comments it's reasonably easy to use and the resulting format is quite usable.
Here is a bit example:
http://87.216.217.107/raydoc/files.html
Currently only 3 documented atexit.h functions and raydium_anim_model_load(from RW, not R) from anim.h also is documented.
Here the resulting atexit.h file in doxygen format. My personal opinion is reasonable good about this format.
http://paste.debian.net/43570

Opinions?


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Sat Aug 08, 2009 12:12 am 
Offline
User avatar

Joined: Sun Mar 16, 2003 2:53 am
Posts: 2591
Location: gnniiiii (Scrat)
OK, right, thanks for the explanations about the goal of this week-end, I didn't understand that at first. I looked to me like some sort of "rush" to commit a new documentation system until Monday.

About the current documentation system, there's 3 points :
- 1 - The input format. I'm OK with you about the "non standard wiki" style, but let's be honest : we use very few features, mostly bold (**), mono font (##) and code (%%). I doesn't looks like something horribly complex to parse, is it ? And about the 40 chars/line limit, I'm not sure, but I think you're talking about 80 chars/line one, and it's only a matter of header source "indentation", not a limit of the format/script.

- 2 - The output format. Again, the current script was a one shot try. I quickly wrote this, I was pleased with the current ouput and that's it. I can update it, we can rewrite it to generate whatever is needed (and even Doxygen format, why not), it's only a matter of user request. We can even rewrite it in pure C or even ASM, I doesn't care :)
In facts, I can't remember of any user request about the documentation so far ... that's probably why the output never changed. That doesn't mean the output can't change or that I don't want it to change !

About Doxygen, I'll try to keep my comment simple: The ouput looks horribly complex to me. The information is spread over many pages, there's a bunch of "tabs" on top, with no visible logic, I must browse files to browse functions ... The general workflow is Doxygen-typic: scrambled. Please, do not misinterpret my message, I don't say the Doxygen output is completely unusable, but it adds nothing to our current antic documentation (even if it's more pretty and light, I admit), I would even say it removes features. And then comes the input syntax: it's rubbish. Really. "code/encode" ? "/*}" ? "/*!<" ? ... and a bunch of HTML tags in the middle. Tasty :) Even Javadoc is better on this point ...

I've wrote enough comments with this stupid syntax to know that I don't want to write more. So.

To make it simple, I think the important things are: our current header doc format. it's simple, It works, so there's no point to fix it, and the ouput should be crystal clear to the standard-newbie-user.

Until we don't touch to these two points, we can change everything to make the ouput better, more easy to browse, make the tweaking easy, the generation more simple, ...

The first step would simply be to collect user needs. How do we currently use the doc ? What can't we do with this doc ? What can be interesting ?

Please, remember that all this is just my opinion. But spending hours and hours, with many people, to switch by hand to Doxygen doesn't look like a good idea to me. There's so much other things to do in the project ! ;)


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Sat Aug 08, 2009 2:10 pm 
Offline

Joined: Sun Dec 28, 2008 1:07 pm
Posts: 3
I'd like to add my voice in support of updated API docs. I've been lurking around Raydium for a while but recently decided to dig deeper into the code for some personal projects. As this is my first post let me take this chance to say thank you for such an elegant and flexible engine. I know I should be a Real Man (tm) and simply work out the API by reading the source code. But as a newbie user to raydium (for real projects) I would really appreciate an updated doc, and one I can generate myself from the source code. Right now I can't generate a local set of docs, it doesn't generate anything you can use outside of a custom wiki, even if it was a cool and quick hack.

Raydium is such a great engine to learn with, I'm learning a lot, for which I'm grateful. It's just a pity the docs can't be more 'accessible' and updated than they are right now. I do appreciate there are more important and cool things to do with Raydium, but improved docs would be desirable for me, and I'm sure others. Xfennec, I appreciate your points about Doxygen being a little heavy and overly complex. Would something like ROBODoc be more suitable or acceptable to you? ROBODoc (http://www.xs4all.nl/~rfsber/Robo/robodoc.html) seems to fit the Raydium spirit better, clean, elegant, simple. Here's an example output http://www.xs4all.nl/~rfsber/Robo/Multi ... index.html.

Failing any changes to the existing doc system, would it be possible to have raydoc.php tweaked to at least output Dokuwiki format or some other format that we can make use of. I want to spend my time tweaking and experimenting with some new Raydium shaders, not learning php doc parsing :-). Either way, thanks again for Raydium, and for considering newbie weirdos like me, who will happily read API docs, and not just the source code ;-).


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Sat Aug 08, 2009 2:43 pm 
Offline
User avatar

Joined: Sun Mar 16, 2003 2:53 am
Posts: 2591
Location: gnniiiii (Scrat)
Thanks for your message. Can I sum up a bit ?
- You want to be able browse the doc locally
- You want to be able to generate the doc locally

Did I miss something here ?


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Sun Aug 09, 2009 5:57 am 
Offline

Joined: Sun Dec 28, 2008 1:07 pm
Posts: 3
Hi,

Thanks for the response. Concerning your summary - Yes, it would be helpful to be able to generate the API docs locally, and to be able to browse them locally. Right now I can't do that (yes raydoc.php produces an output, but not one I can use).


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Sun Aug 09, 2009 4:57 pm 
Offline
User avatar

Joined: Sun Mar 16, 2003 2:53 am
Posts: 2591
Location: gnniiiii (Scrat)
OK.
Let's turn this post to a feature request: to anyone here using/developing Raydium: post your comments about the documentation, describing what you want for a perfect documentation system :)


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Sun Aug 09, 2009 8:12 pm 
Offline
User avatar

Joined: Thu Sep 29, 2005 2:59 pm
Posts: 828
Here my list:

-one page per function (sorry, it's my preference)
-all functions 100% documented. No more "Internal use" only
-all functions must have "a description, detailed parameters, detailed return, and warnings, todo, notes, bug, deprecated if needed)
-buildable from local
-direct html(or XHTML) output
-latex (or directly PDF) output, or conversion script from html
-optionally "search" builtin form (If I type move_3f it should return a page with links to all functions containing that string in their name)


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Sun Aug 09, 2009 10:31 pm 
Offline
User avatar

Joined: Sun Mar 16, 2003 2:53 am
Posts: 2591
Location: gnniiiii (Scrat)
vicente wrote:
-all functions must have "a description, detailed parameters, detailed return, and warnings, todo, notes, bug, deprecated if needed)

I'm OK with you on most other points, but come on, let's be realistic, this particular point will take ages to create and is completely useless in most cases ... What's the point of detailing the parameters r, g, and then b of void raydium_background_color_change(GLfloat r, GLfloat g, GLfloat b, GLfloat a) ?! The doc will looks like all these sanitized documentations where, when you read it, you've this clear feeling that developers were just trying to fill every field just to say "I've completed the doc". I don't want a boring documentation.

IMHO, spending so much work rewriting all documentation is not a good idea, believe me ... Developer don't like to write docs, it's a fact. Trying to make the process even more "strict" and annoying will not help at all. Let's correct the current documentation, step by step, were it needs it (and I'm OK on this point, there's many improvement areas) and spend time into the code. There's quite a few missing and unfinished features in the engine that are properly unacceptable ! THAT is a serious trouble.


Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Thu Sep 10, 2009 5:24 pm 
Offline

Joined: Tue Jul 08, 2008 2:37 am
Posts: 181
Hi!

While writing the documentation for the upcoming lens flare effect system, I've modified the raydoc.php script to generate a kind of a HTML file. This really helps me to quickly check my changes in the API reference.

With the modification, you can generate to documentation the usual way as now, but when providing a "html" parameter it'll try to create a HTML file you can use to quickly see your local changes. Here's an example output file using the "php raydoc.php html > raydoc.html" command: raydoc.html

As you can see, most of the features the Wiki provides are not available, but for me it's an option to see if my documentation syntax is valid, so I'm able to check it before committing my changes to the trunk. ;)

Here's also the raydoc-html.patch if you want to try and use it yourself.
When you like this kind of documentation generation we could improve it to support more Wiki features.

What do you think? Is this useful for anybody else? Should I commit the changes to the trunk?

Best regards,
st


Last edited by st on Wed Feb 15, 2012 6:38 pm, edited 1 time in total.

Top
 Profile  
 
 Post subject: Re: Doc weekend
PostPosted: Thu Sep 10, 2009 7:18 pm 
Offline
User avatar

Joined: Sun Mar 16, 2003 2:53 am
Posts: 2591
Location: gnniiiii (Scrat)
Well, if it's probably too soon to commit, it's a good start. The next step would be to define (once for all) what "syntax features" we use in the documentation, and code a full "transformer" to HTML. And add proper HTML headers ;)

Just a few notes : The most difficult part is to deal with "symmetric" symbols (##, **, %%) using some state variables (or something like that). We should use as most basic HTML tags as we can, but we may have to use a few span tags with a custom CSS (## and %% for instance).

I'm ready to help here, if needed.


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 12 posts ] 

All times are UTC


Who is online

Users browsing this forum: No registered users and 35 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
cron
Powered by phpBB® Forum Software © phpBB Group