duojs/duo — pull request #325 by MatthewMueller (2014-09-12 23:01:36+00:00)
Title: Clarify all internal methods

After a long chat with @lancejpollard it became clear that it's difficult to get up to speed with how Duo works internally. This will inevitably lead to fewer contributions.

This PR attempts to clarify a lot of the confusion without refactoring the library. This PR is the result of me going line by line through Duo's source and asking, "does this make sense?" and "is there a better way to represent this?".

The important internal method docblocks now have the signature:

```js
/**
* Short description
*
* Additional bullet points
*
* Examples
*
* Method signature
*/
```

The work is not finished yet, but hopefully this will open up the "Duo black box" :-)

The next step is to refactor out `duo#resolve(dep, file, entry)`. That way we could potentially offer a plugin based solution to BYOR (bring your own resolver :-P)

Additionally, I think we can break out the flow a bit more in `duo#dependencies()` so it's easier to test separately. This PR (https://github.com/duojs/duo/pull/319) solves this, but it does so at the expense of adding significant verbosity. I think we can get separate the flow and keep method names clean by separating methods out into separate classes / files or breaking out these pieces into separate repos.