Updated API?

Related to the development libraries, released by Curt Binder
Post Reply
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Updated API?

Post by lnevo »

Is there a later copy of the Library Reference? The link on the website page shows it hasn't been updated since 2010-11-17. I don't see any info on some of the newer functions like DelayedStart and Moonphase, etc... Perhaps I'm missing a link somewhere?

Thanks
rimai
Posts: 12881
Joined: Fri Mar 18, 2011 6:47 pm

Re: Updated API?

Post by rimai »

No :(
We kind of need that, I know.
Would you like to help put one together?
jpalmer was going to start one, but I'm not sure how far he went with it.
Roberto.
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Re: Updated API?

Post by lnevo »

Well, would be nice if I had my controller first... my point was to start getting familiar with the API so I could hammer out the code when it arrives. I'd be happy to assist once I get some experience with the code base. I could probably script something to go through the header/cpp files and pull out functions and generate some base html code, or find some other open source tool that can do it.. :)

Update: Maybe this would work... http://www.stack.nl/~dimitri/doxygen/index.html

Once I get everything running I can take a stab at it...
binder
Posts: 2871
Joined: Fri Mar 18, 2011 6:20 pm
Location: Illinois
Contact:

Re: Updated API?

Post by binder »

lnevo wrote:Well, would be nice if I had my controller first... my point was to start getting familiar with the API so I could hammer out the code when it arrives. I'd be happy to assist once I get some experience with the code base. I could probably script something to go through the header/cpp files and pull out functions and generate some base html code, or find some other open source tool that can do it.. :)

Update: Maybe this would work... http://www.stack.nl/~dimitri/doxygen/index.html

Once I get everything running I can take a stab at it...
Yes, we were discussing using Doxygen to generate the API but like Roberto said, we never really got far with it. The libraries have changed rather quickly which made it hard to keep up. We just need to sit down and start documenting it better.
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Updated API?

Post by lnevo »

Ok, so I'll play with Doxygen a bit, see what I can extract, etc.

Maybe it can add comment blocks to the code to make it easier for you guys. if not, I can see what I can do...

Any pointers on which files would be best to start with for pulling out the useful functions? As I said, I'm just getting started...

Lee
binder
Posts: 2871
Joined: Fri Mar 18, 2011 6:20 pm
Location: Illinois
Contact:

Re: Updated API?

Post by binder »

yeah a comment block above the function would be good. starting with reefangel.h and cpp would be good. that file combo contains probably 90% of the functions used.
Piper
Posts: 296
Joined: Fri Jul 20, 2012 7:13 am
Location: Oakley, CA

Re: Updated API?

Post by Piper »

I just started browsing the API myself a day or two ago thought the same thing. I checked out Doxygen real quick and at least it gives you a list of methods and a nice link to the actual code right out of the chute with minimal config.

I'd be more than willing to help out if you need it. I'm not the greatest C++ programmer but I can make heads and tails of the code so far and follow the logic for the most part. If nothing else I can help stub out the current libs to make Doxygen work better down the road. I'd definitely need to read up a bit more on Doxygen if that's the way you want to go.

~Charlie
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Re: Updated API?

Post by lnevo »

So here's the initial dump from Doxygen http://www.easte.net/RA/html

Definitely nice to browse around and give a quick way to search for functions, etc.

Now I need to see if there's a way to add stubs for the commenting... then we need commenters :)
Last edited by lnevo on Thu Aug 09, 2012 6:35 am, edited 1 time in total.
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Updated API?

Post by lnevo »

Ok, so for tonight's progress, I was able to create a fork and have a copy now on my Mac of the Libraries repo from github. As a first step, I added mainpage.h and committed it. This has the "what is reef angel" text from the home page which now shows up on the main Doxygen page.

This was just a test to make sure if I work on any commenting, I can submit a pull request for you guys to grab and keep my copy in sync with the main repo as upstream. This is my first time with git, so forgive me. My repo is at http://github.com/lnevo/Libraries

Next up will be to start with some comment blocks and see what I can make out of the functions.

Overall, it seems that all you need to do is put a /// instead of // comment block before each function... If we can get a few people to attack this we could probably document it pretty quickly and have a nice reference that would be easy to keep up to date.

Also, I'm currently indexing the entire Libraries tree...there are probably a few that can be skipped, let me know if that's the case and I can figure out how to setup the excludes...I figure for now, might as well have everything included since it does a pretty good job indexing everything as-is.

Lee
binder
Posts: 2871
Joined: Fri Mar 18, 2011 6:20 pm
Location: Illinois
Contact:

Re: Updated API?

Post by binder »

yes the triple slash is the easiest at times. there is also the older c style as well. inside those blocks there are special tags you can use for various links, etc.
i used to use it often for some visual c++ code many years ago and i had macro scripts that just prompted me for descriptions. I will look and see if i can find some of them as it might help.
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Updated API?

Post by lnevo »

Awesome. I'm going to work on porting the info from the current reference into the code tonight. And my controller is now in NY...hopefully today or tomorrow for delivery :)
Piper
Posts: 296
Joined: Fri Jul 20, 2012 7:13 am
Location: Oakley, CA

Re: Updated API?

Post by Piper »

Very nice lnevo! I can definitely help with adding the comments if that helps.

Roberto/Kurt - do you want to set the standards on the style here?

I don't want to jump the gun and step on your toes already :)
rimai
Posts: 12881
Joined: Fri Mar 18, 2011 6:47 pm

Re: Updated API?

Post by rimai »

Super Cool!!!
I have no restrictions :)
This is a community effort and I think you guys got a handle of things!!!
Roberto.
Piper
Posts: 296
Joined: Fri Jul 20, 2012 7:13 am
Location: Oakley, CA

Re: Updated API?

Post by Piper »

Cool! lnevo - I haven't used GitHub yet. Can you tell me what I need to do to access your repository to make edits?
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Re: Updated API?

Post by lnevo »

Piper,

It looks like you'll first need to setup an account on github. Then you can make your changes. They have some good howtos on how to submit the changes and setup your fork..

Forking: https://help.github.com/articles/fork-a-repo
Pull Request: https://help.github.com/articles/using-pull-requests/

If you want to fork my copy and I can manage the accumulation of all the comments and then we can give one pull request to Roberto, that might make it easier for Roberto to manage. Unless he wants everyone to send individual requests.. although it might be best if you setup directly from the main stream...

Roberto, what's easier for you?
rimai
Posts: 12881
Joined: Fri Mar 18, 2011 6:47 pm

Re: Updated API?

Post by rimai »

Easier is to get just one pull request from you :)
The libraries actually have 2 branches.
master - released version
dev - working version with updates made to the libraries, but not yet released.
When I release a libraries update, I simply merge the dev into the master.
So, if you are going to fork, I suggest the dev and send pull requests also on dev branch.
I want to refrain from merging stuff to master as they are the released version.
You will eventually see some other branches occasionally. They are usually called issue#xx, where xx is the issue number in our github issue tracking system.
These branches are branched from dev and are not functional. They are work in progress. When they get finalized, they get merged into dev again and the branch is deleted.
Roberto.
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Re: Updated API?

Post by lnevo »

Excellent, I'll reset my fork tonight to use the dev branch. And on thinking about it, would be better for me to consolidate the comments so I can have everything in my branch when I run Doxygen. I'll setup a repo also for the Doxygen output which you can pull later to put on the main website...
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Re: Updated API?

Post by lnevo »

Just thought I'd post this as a reference to anyone that wants to contribute. This is the Doxygen comment syntax reference. The first section up until it goes into the python reference is a good intro..

http://www.stack.nl/~dimitri/doxygen/docblocks.html
binder
Posts: 2871
Joined: Fri Mar 18, 2011 6:20 pm
Location: Illinois
Contact:

Re: Updated API?

Post by binder »

lnevo wrote:Excellent, I'll reset my fork tonight to use the dev branch. And on thinking about it, would be better for me to consolidate the comments so I can have everything in my branch when I run Doxygen. I'll setup a repo also for the Doxygen output which you can pull later to put on the main website...
Sounds good. I do have a suggestion too. In addition to having the HTML indexed pages, could you also generate the PDF as well? Would be nice to have a "static" version available for offline viewing. Just a suggestion.

Side note: I used to use this style when I did lots of my coding.

Code: Select all

for functions, placed in the header file before the function
/** Brief comment here that ends with the period.
 *
 * Detailed comment down here
 * 
 * \param P1 first parameter
 * \param P2 second parameter
 * \return the value from the function
 * \sa Fun1()
 */

for variables, placed in the header file
int var1;  ///< variable for holding a value
I used a combination of the javadoc and qt style of comments when I commented in my C/C++ programs. I also have mixed feelings about placing those code comments in the code (.cpp) files. My thoughts were to keep it all in the header file so it's really easy to access. You just open up the header file and the interface is right there and explained for you....no having to open up multiple files and search through all the blocks of code to find everything. Also, if it was a library file, you would only have access to the header file and thus not being able to look through the code. Anyways, that's something we don't have to worry about. Just thought I'd offer up some additional input on the topic.

Like Roberto said, there's no specific way to do it but my suggestion would be to pick a style / format that you want to use and then do it all that way. Once you pick a style and get things going, make a post / comment / whatever saying "ok guys, this is how we are going to comment our functions and variables. we need you to use it like this...." and then spell it out for us. This way when we are adding functions in, we will have the style down and know what we need to do to ensure it will work properly with Doxygen. :)

This will be very cool. I'm excited to have you helping out and doing all this stuff. Just shows how great open source is. :geek:
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Re: Updated API?

Post by lnevo »

Curt, since you're doing a lot of the programming and you've used it before and probably have still some macros available, I propose we use your format :)

I'm finishing up my setup, just got everything re-wired in my stand so will probably spend a few more days fixing stuff in the code before moving back to the commenting business :)

The PDF output is going to be a little harder, because a lot of the ghostscript utilities are not installed on my mac, and my ports collection is not working. At some point I'll try and get them installed and see what I can do... in the meantime, I've generated the latex output which has the Makefile to create the pdf... I just discovered I don't even have make installed... how is that possible???
binder
Posts: 2871
Joined: Fri Mar 18, 2011 6:20 pm
Location: Illinois
Contact:

Re: Updated API?

Post by binder »

that works. i will do some more digging tomorrow to get my scripts and my style format and such.

as for the makefile i am not sure. i don't think it's a default tool on the mac unless xcode is installed but I'm not positive. i do know that the windows version of doxygen can output pdf... just requires more investigating.
Piper
Posts: 296
Joined: Fri Jul 20, 2012 7:13 am
Location: Oakley, CA

Re: Updated API?

Post by Piper »

Lee - I'm going to have some time later this week and next to work on the docs a little bit. Have you done much on this yet? I want to make sure I'm working with the latest material and not reworking anything you have done already.

~Charlie
User avatar
lnevo
Posts: 5430
Joined: Fri Jul 20, 2012 9:42 am

Updated API?

Post by lnevo »

Not a thing unfortunately...haven't had the time and truthfully, just browsing the API was good enough since the code is so well written!
Piper
Posts: 296
Joined: Fri Jul 20, 2012 7:13 am
Location: Oakley, CA

Re: Updated API?

Post by Piper »

I ended up not having all that much free time after all and didn't get much of a chance to work on it. I've been working on something else that I need to finish up first. Once I get that done I'll come back and revisit this.

~Charlie
Post Reply