Files API Documentation (milestone main issue)

[schomatis]

The title is a bit misleading, this encompasses more than just adding some documentation to the ipfs files commands, my main target is a user who wants to know some of the inner workings of how are files implemented in IPFS and could follow some of the source code involved (to maybe become himself a contributor to the project instead of just a user). Some major points in order to achieve that could be:

1. High level architecture document (inside docs) that could serve as a starting point on where to go looking for the code.

2. Meaningful comments for key data structures and the methods they implement.

3. Refactoring of variable and function names to make them more readeble and descriptive, I would favor legibility instead of compactness (IMO).

4. [Optional and more aggressive modifications] Refactor some code paths to make the code easier to follow.

(The milestone doesn't have all the text formatting capabilities of an issue so I'll document the milestone itself here.)

[Mr0grog]

Would writing a short example/tutorial of creating a Go application that does something with the files API (adds a file? lists your files?) be a good way to identify or demonstrate what’s most ugly/confusing/hard-to-explain inside the go-ipfs package? It would be wonderful to have that example for documentation, too :)

[schomatis]

@Mr0grog Yes! Actually I'm working on something like that in #5052 (I'm glad we're aligned on this), I'll ping you when I have it at a more mature stage to get your feedback.