docs: add an OVERVIEW file

It has been difficult to know the ownership and other things of
nautilus over the time. To not spend again so much time on it, it would
be helpful to have a short overview of nautilus internals.

For that, add a markdown file that explains general concepts and
behaviors of the internals of nautilus.

For now I explained the file, directory and view ownership, to avoid
future confusions and leaks which are kind of catastrophic in Nautilus.

1 files changed, 26 insertions, 0 deletions

diff --git a/OVERVIEW b/OVERVIEW
new file mode 100644
index 000000000..a4d42060a
--- /dev/null
+++ b/OVERVIEW
@@ -0,0 +1,26 @@
+= File Ownership =
+In the minimal case, a nautilus file is owned by:
+- Window slot -> viewed_file
+- Window slot -> history list using bookmarks
+- Path bar -> button -> file
+- Path bar -> button -> nautilus_drag_slot_proxy
+
+When a file is a bookmark, nautilus application keeps a list with them, so it
+also owns those files.
+
+Window slot is the creator of the file if the file was already not present due
+to be a bookmark.
+
+= Directory Ownership =
+Every file has a directory associated, that is usually the parent. However, when
+the file is a root and has no parent, the file is called self_owned, and the directory
+and the file are the same location, but diferent objects.
+
+It's better to always deal with files instead of directories, and let the file handle
+the ownership of its associated directory.
+
+= View Ownership =
+It's owned by:
+- Window slot as a strong reference, since the view sinks the floating reference.
+So to freed it the window slot needs to destroy it with gtk_widget_destroy ()
+since it's the container, but also needs to unref it.