From: Michael S. <mi...@st...> - 2013-02-16 17:52:23
|
Can anyone recommend a good process for documenting a function call tree? The sync_links, delete_orphan_links, and scan_links processing is quite involved between the PLM and the devices. There is a lot of this calls that .. and callback for this or that ..; I can't seem to keep it all in my head at one time over a week or two (part time of course). I especially imagine that I'll not remember it in 6 months. I don't mind spending some time writing it up; I already some have text notes on the various processes. I am really good in Visio for my day job but I don't write software for a living so I'm not in the know about software process documentation. I have lots of ideas about how to use the packaged Visio templates but would really appreciate experience of someone that has done this before. I'm not looking for automation necessarily just a good tool and some examples of how to use it for software documentation. Can anyone recommend 1) a software package commercial or open source and 2) have an example in that software of a function call tree? Sincerely, Michael |
From: Marc M. <ma...@me...> - 2013-02-17 04:07:12
|
On Sat, Feb 16, 2013 at 11:52:29AM -0600, Michael Stovenour wrote: > Can anyone recommend a good process for documenting a function call tree? The sync_links, > delete_orphan_links, and scan_links processing is quite involved between the PLM and the > devices. There is a lot of this calls that .. and callback for this or that ..; I can't > seem to keep it all in my head at one time over a week or two (part time of course). I > especially imagine that I'll not remember it in 6 months. I don't mind spending some time > writing it up; I already some have text notes on the various processes. I am really good > in Visio for my day job but I don't write software for a living so I'm not in the know > about software process documentation. I have lots of ideas about how to use the packaged > Visio templates but would really appreciate experience of someone that has done this > before. I'm not looking for automation necessarily just a good tool and some examples of > how to use it for software documentation. Can anyone recommend 1) a software package > commercial or open source and 2) have an example in that software of a function call tree? It may sound crazy, but a lot of people in the linux world use ascii art. Here's something I have in an arduino piece of code of mine: // Shiftregister connection description: // MC14094 input: Arduino digital pin 2=Clock, pin 3=Data, pin 4=Strobe // MC14094 output: Q8=DB4, Q7=DB5, Q6=DB6, Q5=DB7, Q4=E, Q3=RW, Q2=RS, Q1=None // http://www.ee.mut.ac.th/datasheet/MC14094.pdf // // +--------------------------------------------+ // | Arduino (ATMega 168 or 328) | // | D02 D03 D04 | // +----+-------------+-------------+-----------+ // |4 |5 |6 // |1 |2 |3 // +----+-------------+-------------+-----------+ // | Strobe Data Clock | // | MC14094 8-bit shift/latch register | // | Q8 Q7 Q6 Q5 Q4 Q3 Q2 Q1 | // +----+----+----+----+----+----+----+----+----+ // |11 |12 |13 |14 |7 |6 |5 |4 // |11 |12 |13 |14 |6 |5 |4 // +----+----+----+----+----+----+----+---------+ // | DB4 DB5 DB6 DB7 E RW RS | // | LCD KS0066 | // +--------------------------------------------+ // // 3 Pins required from the Arduino for Data, Clock, and Enable/Strobe. Of course, if you're using some kind of html mail reader, it's not going to look good :) Otherwise, just use what's easier for you and check in a format easy to read for others, either an image file, or a pdf. Hope this helps. Marc -- "A mouse is a device used to point at the xterm you want to type in" - A.S.R. Microsoft is to operating systems .... .... what McDonalds is to gourmet cooking Home page: http://marc.merlins.org/ |
From: Michael S. <mi...@st...> - 2013-02-17 18:33:34
|
On Feb 16, 2013 Marc wrote, > > On Sat, Feb 16, 2013 at 11:52:29AM -0600, Michael Stovenour wrote: > > Can anyone recommend a good process for documenting a function call tree? The > > It may sound crazy, but a lot of people in the linux world use ascii art. I don't think there are enough hours in the day to document all the MH Insteon code in ASCII art ;) > Of course, if you're using some kind of html mail reader, it's not going to look good :) That ASCII art looks just fine in my HTML reader, Outlook 2010 (don't judge me). > Otherwise, just use what's easier for you and check in a format easy to read for others, > either an image file, or a pdf. I was hoping someone would chime in with here's one tool and a web link to an example of a function call tree. I may just paste my notes up on Github for posterity. Thank you, Michael |
From: Marc M. <ma...@me...> - 2013-02-17 18:37:19
|
On Sun, Feb 17, 2013 at 12:33:59PM -0600, Michael Stovenour wrote: > On Feb 16, 2013 Marc wrote, > > > > On Sat, Feb 16, 2013 at 11:52:29AM -0600, Michael Stovenour wrote: > > > Can anyone recommend a good process for documenting a function call tree? The > > > > It may sound crazy, but a lot of people in the linux world use ascii art. > > I don't think there are enough hours in the day to document all the MH Insteon code in > ASCII art ;) Maybe not all of it, but if there is one complicated path, sometimes just a few lines of ASCII do the job. I don't know that it's relevant to what you're doing though. > > Of course, if you're using some kind of html mail reader, it's not going to look good :) > That ASCII art looks just fine in my HTML reader, Outlook 2010 (don't judge me). I don't really care about what tool people use as long as it works :) > > Otherwise, just use what's easier for you and check in a format easy to read for others, > > either an image file, or a pdf. > I was hoping someone would chime in with here's one tool and a web link to an example of a > function call tree. I just remembered something after writing the last Email. It doesn't help with function calls, but when I want to document complex object, I ust perl's Data::Dumper to pretty print the hash, and paste that in the code comments. It really helps to see what an object looks like. I haven't found how to do this with functions though. Marc -- "A mouse is a device used to point at the xterm you want to type in" - A.S.R. Microsoft is to operating systems .... .... what McDonalds is to gourmet cooking Home page: http://marc.merlins.org/ |
From: Kevin R. K. <ke...@kr...> - 2013-03-06 21:09:02
|
Michael, I stumbled on these two websites today, which we could use to diagram various things in MH. I made a quick markup in both of them: http://www.asciiflow.com/#Draw8462102179960324255/463552981 https://cacoo.com/diagrams/0vF11634WdtJ8tqS# The first one allows anyone with the URL to edit. As simple ASCII art, it could be quickly added to a wiki. The second one is a little more sophisticated, but that also makes the learning curve more steep. If you want to play around and edit the second one, let me know, I think I have to send an invite from the website. It appears that I can have up to 15 editors on a single document. Kevin |
From: Michael S. <mi...@st...> - 2013-03-26 04:33:58
|
I found an interesting tool and used it to create the UML for the Insteon classes. Take a look: https://github.com/hollie/misterhouse/wiki/Design-details BTW, the Github wiki is very archaic as wikis go. I suspect you will find it worse than wikispaces. It is significantly worse than mediawiki or tikiwiki based sites. Creating that page "required" creating a clone repository and checking in the images. The images cannot be scaled by the wiki markup so I had to create scaled versions. It took a couple of tries to get it somewhat acceptable. From: Kevin Robert Keegan [mailto:ke...@kr...] Sent: Wednesday, March 06, 2013 3:09 PM To: Marc MERLIN Cc: Michael Stovenour; The main list for the MisterHouse home automation program Subject: Re: [mh] Function Call Documentation Michael, I stumbled on these two websites today, which we could use to diagram various things in MH. I made a quick markup in both of them: http://www.asciiflow.com/#Draw8462102179960324255/463552981 https://cacoo.com/diagrams/0vF11634WdtJ8tqS# <https://cacoo.com/diagrams/0vF11634WdtJ8tqS> The first one allows anyone with the URL to edit. As simple ASCII art, it could be quickly added to a wiki. The second one is a little more sophisticated, but that also makes the learning curve more steep. If you want to play around and edit the second one, let me know, I think I have to send an invite from the website. It appears that I can have up to 15 editors on a single document. Kevin |
From: Kevin R. K. <ke...@kr...> - 2013-03-26 04:48:09
|
On Mon, Mar 25, 2013 at 9:35 PM, Michael Stovenour <mi...@st...>wrote: > I found an interesting tool and used it to create the UML for the Insteon > classes. Take a look:**** > > https://github.com/hollie/misterhouse/wiki/Design-details**** > > ** > Wow, those are some nice command line entries. That certainly helps. |
From: Marc M. <ma...@me...> - 2013-03-26 05:04:04
|
On Mon, Mar 25, 2013 at 11:35:18PM -0500, Michael Stovenour wrote: > I found an interesting tool and used it to create the UML for the Insteon classes. Take a > look: > > https://github.com/hollie/misterhouse/wiki/Design-details Thank you for posting this, it definitely helps out a lot to have an overview like this when you're staring at thousands of lines of code with data structures that aren't formally defined with comments. Thanks much, Marc -- "A mouse is a device used to point at the xterm you want to type in" - A.S.R. Microsoft is to operating systems .... .... what McDonalds is to gourmet cooking Home page: http://marc.merlins.org/ |