Fred's firmware development diary comments thread

[jharvey]

Mate, Abe just pointed out that the index is boring as hell. I just googled and found it can be improved quite easily. I'd like to see that stuff and the config you use to generate it included in the release so that it's JUST a matter of generating it for you

Oops my bad, I had included it with 0.0.17, but for got to add that to the zip file. I think it's best to not have multiple copies of almost the exact same file out there, so I'm not planning on adding it to the SF zip. I just uploaded it to the below link, and I'll try to remember to include it in the next zip version.

http://freeems.sourceforge.net/doxygen/ ... 8/Doxyfile

This file is made entirely from the Doxywizard. For each release my plan it to copy the old Doxyfile from the previous release, to the new, then update the location(s) and rerun doxygen. The generated folder and the Doxyfile get compressed. I simply forgot to select the Doxyfile when I told it to compress.

Also, I can update the existing docs to work a lot better with it...

That self documenting stuff it nice, certainly no complaints from me about doing it. However perhaps that should be a little lower priority, with making her go higher on the list.

Have a look here for the index stuff :

http://lhcb-release-area.web.cern.ch/LH ... MainPage.h

and here in general :

http://lhcb-comp.web.cern.ch/lhcb-comp/ ... oxygen.htm

Let's make this as awesome as humanly possible

Thanks for the jump off point, I should be able to look into that better in a day or two.

[Fred]

Oops my bad, I had included it with 0.0.17, but for got to add that to the zip file. I think it's best to not have multiple copies of almost the exact same file out there, so I'm not planning on adding it to the SF zip. I just uploaded it to the below link, and I'll try to remember to include it in the next zip version.

Urrrrr, I sincerely hope I misunderstand you there. You should DEFINITELY NOT be touching my source release after it is released. That is a tagged copy of the source code and should only be created once and never modified and redistributed officially. It's sacred ground you are treading on when you modify a released file. I hope you meant the doxy zip. By multiple copies of same files, did you mean multiple versions of same named files that are actually different? The thing is, I'd like it to be part of the release so that it is under source control too.

This file is made entirely from the Doxywizard. For each release my plan it to copy the old Doxyfile from the previous release, to the new, then update the location(s) and rerun doxygen. The generated folder and the Doxyfile get compressed. I simply forgot to select the Doxyfile when I told it to compress.

OK, I see that A it is ugly B it is a bit hard coded. I think if we use relative paths and/or no paths and a few other changes it could still be included in the source tree under docs/

What you should do is get yourself setup on github and get a fork of the code. Then you can commit an updated 19 file to the project and send me a pull request. I can pull it and then each time you update it, you can send another pull request and it will stay up to date the whole way through. We must be able to clean it up a lot. EG, what are the defaults the app uses? how many of the values in that file are defaults and can be dropped? etc.

That self documenting stuff it nice, certainly no complaints from me about doing it. However perhaps that should be a little lower priority, with making her go higher on the list.

Of course, but I may as well do it as I come across it. I constantly update the docs anyway as I think it's very important, this is just a minor formatting and verbosity thing. I can't do much serious work away from my desk anyway, so I'll probably work on that over the next few days.

Thanks for the jump off point, I should be able to look into that better in a day or two.

No worries, and cool :-)

I guess the main thing is the index page, and next main is my commenting. The config file is less important, but still fairly important IMO. I reckon that a good project should be completely duplicable from source.

Thoughts?

Fred.

[jharvey]

Urrrrr, I sincerely hope I misunderstand you there. You should DEFINITELY NOT be touching my source release after it is released.

I believe I'm not changing anything in the released files. Here's a overview of what I'm doing.

I get a copy of the source from SF, I unzip, it creates a folder, I enter that folder which contains only one folder. I copy the doxyfile at this level next to this folder. I use doxy wizard to update the location processed, which is at a lower level than the doxyfile and folder. This process creates another folder title html, I rename this new html folder to 0.0.1blah. I then zip 0.0.0.1blah and the Doxyfile. This generated Zip is what I put up on the SF download, the folder structure is what I put on the web page.

In 0.0.18, I forgot to include the Doxyfile in this zip. I have not added it to archive, and I have not uploaded a new zip.

I don't think it's all that hard to change the index page. I seem to recall I just tell it to use a different template file.

[Fred]

OK, sweet, my only question is, why do you end up with an extra directory? I'll never ever spam you with a bunch of files in a zip with no parent... I hate people that do that...

Fred.

[Fred]

I've grabbed your doxy setup file and installed graphviz and doxy etc and downloaded the latest doxy zip. I'll be working on making it all sweeter over the next two days :-)

When I get back I'll crack into some functional work, but it's about time I spent some effort on beautifying the code base a bit. Some of it is pretty horrid (by my standards anyway).

I'm feeling so positive about this all. Basically pretty soon it will just be down to Aaron to give me a front end to use and I'll be able to try it on the car :-)

I can't wait!!

Fred.

[jharvey]

OK, sweet, my only question is, why do you end up with an extra directory? I'll never ever spam you with a bunch of files in a zip with no parent... I hate people that do that...

Likely a junk food gui issue. I right click --> "extract to file name" and it extracts to a folder as opposed to right click --> "extract here" which doesn't put them in a sub folder.

I've grown in that habit because others aren't always as nice as you are about the sub folder thing.

[jharvey]

Finally got to read over the Doxygen \mainpage thing. Sounds like it doesn't really change much for me. I can still run Doxygen the way I've been doing it, and you can change your comments to be more Doxygen friendly, if that's what you decide to do.

I made a draft version the section that can be included in the comments. This should make a nicer index page / mainpage. Most of it's taken directly from the wiki welcome page. However it has been changed to make it more firmware / software specific. Also I'm not exactly sure how the release notes and such work, I took a stab, but those might not be right.

Code: Select all

/*! \mainpage FreeEMS
 *  \anchor Doxygen_Home_top
 *
 *Welcome to the FreeEMS, where free means freedom, and open source means open for anyone to read. 
 *
 *FreeEMS is a free Engine Management System. It includes both software and hardware designs for the
 *experimental engine. Have you ever thought that an engine could run better than when it was manufactured,  
 *but haven't been able to make a prototype because it was too large of a task for you to accomplish? Or 
 *perhaps you want to do something special at the race track or on a closed stage. If so then this is the 
 *project for you. Here you will find software and firmware to run on a specific hardware system. The design 
 *files for the hardware system are also posted as free. More information can be found at diyefi web page 
 *<a href="http://www.diyefi.org/">diyefi</a>
 *
 * Items included here are listed below
 * \li Pre-compiled firmware, ready for burning
 * \li Source code that generated the above firmware
 * \li licencing files
 * \li Documents and spread sheets relative to the engineering of FreeEMS
 * \li other suff
 * \li more other stuff I'm sure
 *
 * <p>See also:
 * \li <a href="https://sourceforge.net/projects/freeems/">Sourceforge location</a>
 * \li <a href="http://freeems.aaronb.info/wiki/doku.php?id=start">Wiki location</a>
 * \li <a href="http://www.diyefi.org/forum/index.php">DIYEFI.org location</a>
 * <hr>
 * \htmlinclude new_release.notes
 * <hr>
 *
 * <b>Additional information:</b>
 * \li <a href="../release.notes"><b>Release notes history</b></a>
 * \li <a href="../change.log"><b>Change log history</b></a>
 *
 */

[Fred]

Where do I put that?

You should fork the repo and add it in and push up and send me a pull request so it can have your name on it in the history!

Fred.

[jharvey]

My understanding is that you can put it any where, however if I where going to look for it for updating purposes ect, I would likely look for it near the main block, or perhaps the freeems.c block.

[Fred]

You are correct, it has a nice setup like that. You just define links etc to glue stuff together and put it anywhere you like.

In the car on the way down here I stuck your version in and put it in a file and did a build. Relative paths work by the way, and oh, great minds think alike. It's in freeems.c ;-)

I'll make some changes tonight and over the next few days and the doxygen for 0.0.19 will be fricking awesome, just you wait :-)

Thanks for kick starting that effort. Now that I've read up on it, I think it's an awesome way to document the code and the way it works. And being part of the code it will stay maintained! Brilliant, you're a legend!

Oh, and I also did one for the latest ms2extra... LOL, I'll tidy that up and post it in the non-free section for an item of education.

Fred.