Code cleanup/documentation

[andrewhill157]

We should go through what we have written thus far and clean things up a bit and add some documentation. Things are going to start getting messy and hard to follow if we don't do this soon.

[andrewhill157]

Thanks for having a go at making plotData more modular Tim! (d11bd6d) I think this is a really good start and I mostly understand what is going on. I think there are still a few functions that are doing too much, but this is definitely looking better. Ideally, I would imagine that all the plotting functions (plotLineageTree, plot3DView, etc.) would have the same interface and handle transitions between old and new locations within the functions. It would also be nice if plotData was literally just making function calls as a wrapper function rather than doing other work itself. From what I can tell a few functions (plot3DView for example) are still doing some extra calculations that other plots are then using when they could (potentially) be calculated in a separate function to avoid the inconsistent interfaces. Limiting (as much as possible) the plotting code to plotting rather than making calculations, etc. could make adding new plots easier. We could also separate popover text adding into its own function perhaps?

Anyway, just wondering if you plan to (or already are) still working on this. I don't want to make changes to this part of the code if things are still in flux. Molly's sister has her wedding tomorrow, so I may not be able to make changes myself until Sunday (or maybe tonight if I have time).

[andrewhill157]

I have added function-level documentation to some functions and placeholders to all other functions (I think) in a standard JS documentation format. Particularly for some of the more complicated functions, it would be great to have descriptions of

1. Input parameters
2. Requirements (controls that this function draws on, does something else need to be called first, etc.)
3. Return values
4. Purpose
5. Is this function a callback anywhere?

Tim, I have added some descriptions, but it would be great if you could fill some of these in for the things that you wrote. I haven't finished all of mine yet. I think it would be worth us trying to get this done reasonably soon to make it easier for others to work on. I also think new functions should (if others agree) have this sort of documentation moving forward.

[tdurham86]

Most of the functions now have more detailed documentation. Let me know if there are still any problems, but I think the only undocumented functions now are pretty minor.