Updated API?
Updated API?
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
Thanks
Re: Updated API?
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.
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.
Re: Updated API?
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...
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...
Re: Updated API?
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.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...
Updated API?
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
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
Re: Updated API?
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.
Re: Updated API?
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
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
Re: Updated API?
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
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.
Updated API?
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
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
Re: Updated API?
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.
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.
Updated API?
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
Re: Updated API?
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
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
Re: Updated API?
Super Cool!!!
I have no restrictions
This is a community effort and I think you guys got a handle of things!!!
I have no restrictions
This is a community effort and I think you guys got a handle of things!!!
Roberto.
Re: Updated API?
Cool! lnevo - I haven't used GitHub yet. Can you tell me what I need to do to access your repository to make edits?
Re: Updated API?
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?
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?
Re: Updated API?
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.
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.
Re: Updated API?
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...
Re: Updated API?
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
http://www.stack.nl/~dimitri/doxygen/docblocks.html
Re: Updated API?
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.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...
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
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.
Re: Updated API?
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???
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???
Re: Updated API?
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.
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.
Re: Updated API?
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
~Charlie
Updated API?
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!
Re: Updated API?
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
~Charlie