About Store Forum Documentation Contact



Post Reply 
API Documentation
Author Message
gwald Offline
Member

Post: #1
API Documentation
Edit Subject Changed from Documentation in header to API Documentation.

Hi,
This has been my process thus far using the esenthel libs.

When I get to a non-tutorial situation I find it hard to find the information I need.

Most functions only have a few words of description.
IE:
Rect_RU(Flt x, Flt y, Flt r) ; // right up
Rect_C(Flt x, Flt y, Flt r); // center

No explanation on what the in/outs are or what the function does.

So, I grep the function name in the tuts.
The tuts are well documented, I can usually figure it out after trail and error.

This trail and error is really a waste of time and very frustrating.

I'm not saying document all functions in detail, but the basic -
input
process
ouput

As a plus to better header documentation you can generate a chm from the headers and maybe integrate it into your IDE!

I'm not a newbie at C++ (rusty) nor games programming (rusty).
It just makes it harder then it has to be.

I hope you consider it import, as your engine is a library with header interfaces.
Just giving my feedback.

PS: Helpful window tools:
http://notepad-plus-plus.org/
http://code.google.com/p/grepwin/

My Blog
http://www.esenthel.com/community/showthread.php?tid=6043

I hang out at Esenthel IRC Channel
http://webchat.freenode.net/?channels=#Esenthel
(This post was last modified: 02-21-2013 10:19 PM by gwald.)
02-21-2013 01:54 AM
Visit this user's website Find all posts by this user Quote this message in a reply
Scarlet Thread Offline
Member

Post: #2
RE: Domentation in header
I agree, the process has been very similar for me with testing, trial and error. Luckily it hasn't been too bad and I'm starting to get across it all.

I must say though that I appreciate how this engine doesn't break it's back to make it easy for n00bs and non programmers. The last engine I used was ruined by that.
(This post was last modified: 02-21-2013 04:28 AM by Scarlet Thread.)
02-21-2013 04:27 AM
Find all posts by this user Quote this message in a reply
gwald Offline
Member

Post: #3
RE: Documentation in header
I'm not saying make it noob friendly, and especially not for non programmers.
Everyone here is some kind of developer and knows where and what to look for.. it's just discouraging not finding it and having to guess.

Anyway, just my feedback.

PS: I printed the documentation.chm (chm to pdf)
It's a good doc to have printed but not all pages are print friendly.
Lines go over the page and don't get printed.

My Blog
http://www.esenthel.com/community/showthread.php?tid=6043

I hang out at Esenthel IRC Channel
http://webchat.freenode.net/?channels=#Esenthel
(This post was last modified: 02-21-2013 07:07 AM by gwald.)
02-21-2013 06:58 AM
Visit this user's website Find all posts by this user Quote this message in a reply
Esenthel Offline
Administrator

Post: #4
RE: Documentation in header
Hi,
Thanks for the feedback.
You can provide a list of functions for which the comments are not clear enough and I can improve those comments.
I don't however plan to make extra chm because everything can already be done from browsing engine headers in Esenthel Editor
02-21-2013 11:53 AM
Find all posts by this user Quote this message in a reply
gwald Offline
Member

Post: #5
RE: Documentation in header
Hi,
Not sure if I explained it well.
Using MS VS or eclipse etc you can right click on any var/class/function etc
And see what it does what params to give it and what the output is.

This is just expected with any library.

Regarding the chm, I think having a searchable/printable reference would be worth while.

http://en.wikipedia.org/wiki/Comparison_...generators

A real life example:
http://www.ogre3d.org/docs/api/html

I realise the above isn't improving/expanding anything.
But it would make your product a lot more 'programmer' friendly.

Again this is just my feedback, up to you what you do with your engine wink
I'll leave it to you.

Cheers
Mike.

My Blog
http://www.esenthel.com/community/showthread.php?tid=6043

I hang out at Esenthel IRC Channel
http://webchat.freenode.net/?channels=#Esenthel
(This post was last modified: 02-21-2013 01:10 PM by gwald.)
02-21-2013 12:51 PM
Visit this user's website Find all posts by this user Quote this message in a reply
Esenthel Offline
Administrator

Post: #6
RE: Documentation in header
In Code Editor you can Middle Mouse Button click or do Ctrl+Enter to jump to definition.
It also supports symbol searching with Ctrl+F
All is described in here http://www.esenthel.com/wiki/index.php?t...ode_Editor
02-21-2013 02:03 PM
Find all posts by this user Quote this message in a reply
Post Reply