1 files changed, 64 insertions, 1 deletions

diff --git a/source/blender/editors/screen/screen_intern.h b/source/blender/editors/screen/screen_intern.h
index 47229e5e2b5..bc06e46ba96 100644
--- a/source/blender/editors/screen/screen_intern.h
+++ b/source/blender/editors/screen/screen_intern.h
@@ -61,23 +61,48 @@ typedef enum eScreenAxis {
 #define AREAJOINTOLERANCEX (AREAMINX * U.dpi_fac)
 #define AREAJOINTOLERANCEY (HEADERY * U.dpi_fac)
 
-/* Expanded interaction influence of area borders. */
+/**
+ * Expanded interaction influence of area borders.
+ */
 #define BORDERPADDING ((2.0f * U.dpi_fac) + U.pixelsize)
 
 /* area.c */
+
+/**
+ * we swap spaces for fullscreen to keep all allocated data area vertices were set
+ */
 void ED_area_data_copy(ScrArea *area_dst, ScrArea *area_src, const bool do_free);
 void ED_area_data_swap(ScrArea *area_dst, ScrArea *area_src);
+/* for quick toggle, can skip fades */
 void region_toggle_hidden(struct bContext *C, ARegion *region, const bool do_fade);
 
 /* screen_draw.c */
+
+/**
+ * Visual indication of the two areas involved in a proposed join.
+ *
+ * \param sa1: Area from which the resultant originates.
+ * \param sa2: Target area that will be replaced.
+ */
 void screen_draw_join_highlight(struct ScrArea *sa1, struct ScrArea *sa2);
 void screen_draw_split_preview(struct ScrArea *area, const eScreenAxis dir_axis, const float fac);
 
 /* screen_edit.c */
+
+/**
+ * Empty screen, with 1 dummy area without space-data. Uses window size.
+ */
 bScreen *screen_add(struct Main *bmain, const char *name, const rcti *rect);
 void screen_data_copy(bScreen *to, bScreen *from);
+/**
+ * Prepare a newly created screen for initializing it as active screen.
+ */
 void screen_new_activate_prepare(const wmWindow *win, bScreen *screen_new);
 void screen_change_update(struct bContext *C, wmWindow *win, bScreen *screen);
+/**
+ * \return the screen to activate.
+ * \warning The returned screen may not always equal \a screen_new!
+ */
 void screen_change_prepare(bScreen *screen_old,
                            bScreen *screen_new,
                            struct Main *bmain,
@@ -89,10 +114,24 @@ ScrArea *area_split(const wmWindow *win,
                     const eScreenAxis dir_axis,
                     const float fac,
                     const bool merge);
+/**
+ * Join any two neighboring areas. Might involve complex changes.
+ */
 int screen_area_join(struct bContext *C, bScreen *screen, ScrArea *sa1, ScrArea *sa2);
+/**
+ * with `sa_a` as center, `sa_b` is located at: 0=W, 1=N, 2=E, 3=S
+ * -1 = not valid check.
+ * used with join operator.
+ */
 eScreenDir area_getorientation(ScrArea *sa_a, ScrArea *sa_b);
+/**
+ * Get alignment offset of adjacent areas. 'dir' value is like #area_getorientation().
+ */
 void area_getoffsets(
     ScrArea *sa_a, ScrArea *sa_b, const eScreenDir dir, int *r_offset1, int *r_offset2);
+/**
+ * Close a screen area, allowing most-aligned neighbor to take its place.
+ */
 bool screen_area_close(struct bContext *C, bScreen *screen, ScrArea *area);
 void screen_area_spacelink_add(struct Scene *scene, ScrArea *area, eSpace_Type space_type);
 struct AZone *ED_area_actionzone_find_xy(ScrArea *area, const int xy[2]);
@@ -105,22 +144,46 @@ ScrVert *screen_geom_vertex_add(bScreen *screen, short x, short y);
 ScrEdge *screen_geom_edge_add_ex(ScrAreaMap *area_map, ScrVert *v1, ScrVert *v2);
 ScrEdge *screen_geom_edge_add(bScreen *screen, ScrVert *v1, ScrVert *v2);
 bool screen_geom_edge_is_horizontal(ScrEdge *se);
+/**
+ * \param bounds_rect: Either window or screen bounds.
+ * Used to exclude edges along window/screen edges.
+ */
 ScrEdge *screen_geom_area_map_find_active_scredge(const struct ScrAreaMap *area_map,
                                                   const rcti *bounds_rect,
                                                   const int mx,
                                                   const int my);
+/**
+ * Need win size to make sure not to include edges along screen edge.
+ */
 ScrEdge *screen_geom_find_active_scredge(const wmWindow *win,
                                          const bScreen *screen,
                                          const int mx,
                                          const int my);
+/**
+ * \brief Main screen-layout calculation function.
+ *
+ * * Scale areas nicely on window size and DPI changes.
+ * * Ensure areas have a minimum height.
+ * * Correctly set global areas to their fixed height.
+ */
 void screen_geom_vertices_scale(const wmWindow *win, bScreen *screen);
+/**
+ * \return 0 if no split is possible, otherwise the screen-coordinate at which to split.
+ */
 short screen_geom_find_area_split_point(const ScrArea *area,
                                         const rcti *window_rect,
                                         const eScreenAxis dir_axis,
                                         float fac);
+/**
+ * Select all edges that are directly or indirectly connected to \a edge.
+ */
 void screen_geom_select_connected_edge(const wmWindow *win, ScrEdge *edge);
 
 /* screen_context.c */
+
+/**
+ * Entry point for the screen context.
+ */
 int ed_screen_context(const struct bContext *C,
                       const char *member,
                       struct bContextDataResult *result);