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 »

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