Is there a description of how the Espruino source in github is organized?

Whenever I try to understand the code on github, I always find it to be a very frustrating experience. For example, I was looking at the pin mappings on the board files. So what's this pinutils thing doing? Who knows! Search the repo.... import pinutils, import pinutils, import pinutils. Where is pinutils defined?! I still haven't figured it out... I can build after just cloning the repo, so obviously pinutils is defined somewhere in there, but I'll be damned if I can find it.

Another time I was looking into how Espruino picks which timer to use for analogWrite() to try to improve sanity of it's choices - and I had a similar experience. I couldn't track down where it was making the decisions, so that stymied my attempt at fixing it right at the gate.

This is the sort of experience I have every time I try to work with the Espruino firmware code - I've got no idea how the code is organized, and nothing is where I'd "expect" to find it, and github search always fails me when I try to go hunting for the definitions of things that files refer to.

Not that it will help you with github, but... I use the IDE named 'QTCreator' to work with the code. Then, I have the ability to easily search through all files in the project and find definitions, etc. Maybe some kind of ide is what you need?

Personally I'd forget the GitHub search and use something on your PC instead. About the only thing it seems to work with is the issues list.

The actual file you need is pinutils.py. I think it's in the same directory so it really shouldn't have been too hard to find if search worked.

There's a bit of info about organisation - and what is in each directory - in the readme file. I'm open to additions though - I tend not to think what it would be like for newcomers now :)

@Gordon
I feel the pain @DrAzzy mentions. When trying to better understand functionality or implement a workaround or alternate build it would be useful to reference where functions get defined in source and not have to chronically search. You automate building a lot of the documentation. For someone familiar with the source structure and generation, this seems like a doable addition to extract all functions by the containing source file into a table or adding directly to the reference documentation page.

I'll add an issue for it on GitHub - I guess I could add a link that went to the file and line the function was defined in on GitHub.

... having said that if your editor can do a code-wide search (which pretty much everything should be abe to do now?) just searching for the function's name in double quotes will find you the definition in no time.

Issue here: https://github.com/espruino/Espruino/issues/849