Cleanup: move public doc-strings into headers for 'editors'

Ref T92709

12 files changed, 64 insertions, 263 deletions

diff --git a/source/blender/editors/screen/area.c b/source/blender/editors/screen/area.c
index dc7cbb96e96..5dc6fe88663 100644
--- a/source/blender/editors/screen/area.c
+++ b/source/blender/editors/screen/area.c
@@ -140,7 +140,6 @@ void ED_region_pixelspace(const ARegion *region)
   GPU_matrix_identity_set();
 }
 
-/* only exported for WM */
 void ED_region_do_listen(wmRegionListenerParams *params)
 {
   ARegion *region = params->region;
@@ -169,7 +168,6 @@ void ED_region_do_listen(wmRegionListenerParams *params)
   }
 }
 
-/* only exported for WM */
 void ED_area_do_listen(wmSpaceTypeListenerParams *params)
 {
   /* no generic notes? */
@@ -178,7 +176,6 @@ void ED_area_do_listen(wmSpaceTypeListenerParams *params)
   }
 }
 
-/* only exported for WM */
 void ED_area_do_refresh(bContext *C, ScrArea *area)
 {
   /* no generic notes? */
@@ -443,7 +440,6 @@ void ED_area_do_msg_notify_tag_refresh(
   ED_area_tag_refresh(area);
 }
 
-/* Follow ARegionType.message_subscribe */
 void ED_area_do_mgs_subscribe_for_tool_header(const wmRegionMessageSubscribeParams *params)
 {
   struct wmMsgBus *mbus = params->message_bus;
@@ -507,7 +503,6 @@ static bool area_is_pseudo_minimized(const ScrArea *area)
   return (area->winx < 3) || (area->winy < 3);
 }
 
-/* only exported for WM */
 void ED_region_do_layout(bContext *C, ARegion *region)
 {
   /* This is optional, only needed for dynamically sized regions. */
@@ -531,7 +526,6 @@ void ED_region_do_layout(bContext *C, ARegion *region)
   region->flag &= ~RGN_FLAG_SEARCH_FILTER_UPDATE;
 }
 
-/* only exported for WM */
 void ED_region_do_draw(bContext *C, ARegion *region)
 {
   wmWindow *win = CTX_wm_window(C);
@@ -705,10 +699,6 @@ void ED_region_tag_refresh_ui(ARegion *region)
   }
 }
 
-/**
- * Tag editor overlays to be redrawn. If in doubt about which parts need to be redrawn (partial
- * clipping rectangle set), redraw everything.
- */
 void ED_region_tag_redraw_editor_overlays(struct ARegion *region)
 {
   if (region && !(region->do_draw & (RGN_DRAWING | RGN_DRAW))) {
@@ -786,9 +776,6 @@ void ED_area_tag_refresh(ScrArea *area)
 
 /* *************************************************************** */
 
-/**
- * Returns the search string if the space type and region type support property search.
- */
 const char *ED_area_region_search_filter_get(const ScrArea *area, const ARegion *region)
 {
   /* Only the properties editor has a search string for now. */
@@ -802,9 +789,6 @@ const char *ED_area_region_search_filter_get(const ScrArea *area, const ARegion
   return NULL;
 }
 
-/**
- * Set the temporary update flag for property search.
- */
 void ED_region_search_filter_update(const ScrArea *area, ARegion *region)
 {
   region->flag |= RGN_FLAG_SEARCH_FILTER_UPDATE;
@@ -817,7 +801,6 @@ void ED_region_search_filter_update(const ScrArea *area, ARegion *region)
 
 /* *************************************************************** */
 
-/* use NULL to disable it */
 void ED_area_status_text(ScrArea *area, const char *str)
 {
   /* happens when running transform operators in background mode */
@@ -1271,7 +1254,6 @@ static void region_overlap_fix(ScrArea *area, ARegion *region)
   }
 }
 
-/* overlapping regions only in the following restricted cases */
 bool ED_region_is_overlap(int spacetype, int regiontype)
 {
   if (regiontype == RGN_TYPE_HUD) {
@@ -1926,7 +1908,6 @@ bool ED_area_has_shared_border(struct ScrArea *a, struct ScrArea *b)
   return area_getorientation(a, b) != -1;
 }
 
-/* called in screen_refresh, or screens_init, also area size changes */
 void ED_area_init(wmWindowManager *wm, wmWindow *win, ScrArea *area)
 {
   WorkSpace *workspace = WM_window_get_active_workspace(win);
@@ -2076,15 +2057,11 @@ static void region_update_rect(ARegion *region)
   BLI_rcti_init(&region->v2d.mask, 0, region->winx - 1, 0, region->winy - 1);
 }
 
-/**
- * Call to move a popup window (keep OpenGL context free!)
- */
 void ED_region_update_rect(ARegion *region)
 {
   region_update_rect(region);
 }
 
-/* externally called for floating regions like menus */
 void ED_region_floating_init(ARegion *region)
 {
   BLI_assert(region->alignment == RGN_ALIGN_FLOAT);
@@ -2114,7 +2091,6 @@ void ED_region_cursor_set(wmWindow *win, ScrArea *area, ARegion *region)
   WM_cursor_set(win, WM_CURSOR_DEFAULT);
 }
 
-/* for use after changing visibility of regions */
 void ED_region_visibility_change_update(bContext *C, ScrArea *area, ARegion *region)
 {
   if (region->flag & RGN_FLAG_HIDDEN) {
@@ -2131,7 +2107,6 @@ void ED_region_visibility_change_update(bContext *C, ScrArea *area, ARegion *reg
   ED_area_tag_redraw(area);
 }
 
-/* for quick toggle, can skip fades */
 void region_toggle_hidden(bContext *C, ARegion *region, const bool do_fade)
 {
   ScrArea *area = CTX_wm_area(C);
@@ -2147,15 +2122,11 @@ void region_toggle_hidden(bContext *C, ARegion *region, const bool do_fade)
   }
 }
 
-/* exported to all editors, uses fading default */
 void ED_region_toggle_hidden(bContext *C, ARegion *region)
 {
   region_toggle_hidden(C, region, true);
 }
 
-/**
- * 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)
 {
   const char spacetype = area_dst->spacetype;
@@ -2461,9 +2432,6 @@ void ED_area_swapspace(bContext *C, ScrArea *sa1, ScrArea *sa2)
   ED_area_tag_refresh(sa2);
 }
 
-/**
- * \param skip_region_exit: Skip calling area exit callback. Set for opening temp spaces.
- */
 void ED_area_newspace(bContext *C, ScrArea *area, int type, const bool skip_region_exit)
 {
   wmWindow *win = CTX_wm_window(C);
@@ -2628,7 +2596,6 @@ void ED_area_prevspace(bContext *C, ScrArea *area)
   WM_event_add_notifier(C, NC_SPACE | ND_SPACE_CHANGED, area);
 }
 
-/* returns offset for next button in header */
 int ED_area_header_switchbutton(const bContext *C, uiBlock *block, int yco)
 {
   ScrArea *area = CTX_wm_area(C);
@@ -2950,11 +2917,6 @@ static int panel_draw_width_from_max_width_get(const ARegion *region,
              max_width;
 }
 
-/**
- * \param contexts: A NULL terminated array of context strings to match against.
- * Matching against any of these strings will draw the panel.
- * Can be NULL to skip context checks.
- */
 void ED_region_panels_layout_ex(const bContext *C,
                                 ARegion *region,
                                 ListBase *paneltypes,
@@ -3266,10 +3228,6 @@ static bool panel_property_search(const bContext *C,
   return false;
 }
 
-/**
- * Build the same panel list as #ED_region_panels_layout_ex and checks whether any
- * of the panels contain a search result based on the area / region's search filter.
- */
 bool ED_region_property_search(const bContext *C,
                                ARegion *region,
                                ListBase *paneltypes,
@@ -3475,9 +3433,6 @@ int ED_area_footersize(void)
   return ED_area_headersize();
 }
 
-/**
- * \return the final height of a global \a area, accounting for DPI.
- */
 int ED_area_global_size_y(const ScrArea *area)
 {
   BLI_assert(ED_area_is_global(area));
@@ -3527,12 +3482,6 @@ ScrArea *ED_screen_areas_iter_next(const bScreen *screen, const ScrArea *area)
   return screen->areabase.first;
 }
 
-/**
- * For now we just assume all global areas are made up out of horizontal bars
- * with the same size. A fixed size could be stored in ARegion instead if needed.
- *
- * \return the DPI aware height of a single bar/region in global areas.
- */
 int ED_region_global_size_y(void)
 {
   return ED_area_headersize(); /* same size as header */
@@ -3858,9 +3807,6 @@ void ED_region_cache_draw_cached_segments(
   }
 }
 
-/**
- * Generate subscriptions for this region.
- */
 void ED_region_message_subscribe(wmRegionMessageSubscribeParams *params)
 {
   ARegion *region = params->region;
diff --git a/source/blender/editors/screen/area_query.c b/source/blender/editors/screen/area_query.c
index 30e744ca174..022f8620b0b 100644
--- a/source/blender/editors/screen/area_query.c
+++ b/source/blender/editors/screen/area_query.c
@@ -140,10 +140,6 @@ bool ED_region_overlap_isect_xy_with_margin(const ARegion *region,
           ED_region_overlap_isect_y_with_margin(region, event_xy[1], margin));
 }
 
-/**
- * \note: This may return true for multiple overlapping regions. If it matters, check overlapped
- *        regions first (#ARegion.overlap).
- */
 bool ED_region_contains_xy(const ARegion *region, const int event_xy[2])
 {
   /* Only use the margin when inside the region. */
@@ -193,13 +189,6 @@ bool ED_region_contains_xy(const ARegion *region, const int event_xy[2])
   return false;
 }
 
-/**
- * Similar to #BKE_area_find_region_xy() but when \a event_xy intersects an overlapping region,
- * this returns the region that is visually under the cursor. E.g. when over the
- * transparent part of the region, it returns the region underneath.
- *
- * The overlapping region is determined using the #ED_region_contains_xy() query.
- */
 ARegion *ED_area_find_region_xy_visual(const ScrArea *area,
                                        const int regiontype,
                                        const int event_xy[2])
diff --git a/source/blender/editors/screen/area_utils.c b/source/blender/editors/screen/area_utils.c
index 30553bb7f07..9a688ac0b05 100644
--- a/source/blender/editors/screen/area_utils.c
+++ b/source/blender/editors/screen/area_utils.c
@@ -40,9 +40,6 @@
 /** \name Generic Tool System Region Callbacks
  * \{ */
 
-/**
- * Callback for #ARegionType.message_subscribe
- */
 void ED_region_generic_tools_region_message_subscribe(const wmRegionMessageSubscribeParams *params)
 {
   struct wmMsgBus *mbus = params->message_bus;
@@ -56,9 +53,6 @@ void ED_region_generic_tools_region_message_subscribe(const wmRegionMessageSubsc
   WM_msg_subscribe_rna_anon_prop(mbus, WorkSpace, tools, &msg_sub_value_region_tag_redraw);
 }
 
-/**
- * Callback for #ARegionType.snap_size
- */
 int ED_region_generic_tools_region_snap_size(const ARegion *region, int size, int axis)
 {
   if (axis == 0) {
diff --git a/source/blender/editors/screen/glutil.c b/source/blender/editors/screen/glutil.c
index f651fd4fb61..5f523df18d1 100644
--- a/source/blender/editors/screen/glutil.c
+++ b/source/blender/editors/screen/glutil.c
@@ -57,12 +57,6 @@ static void immDrawPixelsTexSetupAttributes(IMMDrawPixelsTexState *state)
       vert_format, "texCoord", GPU_COMP_F32, 2, GPU_FETCH_FLOAT);
 }
 
-/**
- * To be used before calling #immDrawPixelsTex
- * Default shader is #GPU_SHADER_2D_IMAGE_COLOR
- * You can still set uniforms with:
- * `GPU_shader_uniform_int(shader, GPU_shader_get_uniform(shader, "name"), 0);`
- */
 IMMDrawPixelsTexState immDrawPixelsTexSetup(int builtin)
 {
   IMMDrawPixelsTexState state;
@@ -78,20 +72,6 @@ IMMDrawPixelsTexState immDrawPixelsTexSetup(int builtin)
   return state;
 }
 
-/**
- * Use the currently bound shader.
- *
- * Use #immDrawPixelsTexSetup to bind the shader you
- * want before calling #immDrawPixelsTex.
- *
- * If using a special shader double check it uses the same
- * attributes "pos" "texCoord" and uniform "image".
- *
- * If color is NULL then use white by default
- *
- * Be also aware that this function unbinds the shader when
- * it's finished.
- */
 void immDrawPixelsTexScaled_clipping(IMMDrawPixelsTexState *state,
                                      float x,
                                      float y,
@@ -363,7 +343,6 @@ void immDrawPixelsTex_clipping(IMMDrawPixelsTexState *state,
 
 /* **** Color management helper functions for GLSL display/transform ***** */
 
-/* Draw given image buffer on a screen using GLSL for display transform */
 void ED_draw_imbuf_clipping(ImBuf *ibuf,
                             float x,
                             float y,
@@ -577,8 +556,6 @@ int ED_draw_imbuf_method(ImBuf *ibuf)
   return U.image_draw_method;
 }
 
-/* don't move to GPU_immediate_util.h because this uses user-prefs
- * and isn't very low level */
 void immDrawBorderCorners(uint pos, const rcti *border, float zoomx, float zoomy)
 {
   float delta_x = 4.0f * UI_DPI_FAC / zoomx;
diff --git a/source/blender/editors/screen/screen_context.c b/source/blender/editors/screen/screen_context.c
index 2dc79a0e335..304205d0cc4 100644
--- a/source/blender/editors/screen/screen_context.c
+++ b/source/blender/editors/screen/screen_context.c
@@ -1283,7 +1283,6 @@ static void ensure_ed_screen_context_functions(void)
   register_context_function("ui_list", screen_ctx_ui_list);
 }
 
-/* Entry point for the screen context. */
 int ed_screen_context(const bContext *C, const char *member, bContextDataResult *result)
 {
   if (CTX_data_dir(member)) {
diff --git a/source/blender/editors/screen/screen_draw.c b/source/blender/editors/screen/screen_draw.c
index ab50e327de3..e720ae4b9d8 100644
--- a/source/blender/editors/screen/screen_draw.c
+++ b/source/blender/editors/screen/screen_draw.c
@@ -162,9 +162,6 @@ static void drawscredge_area(ScrArea *area, int sizex, int sizey, float edge_thi
   drawscredge_area_draw(sizex, sizey, x1, y1, x2, y2, edge_thickness);
 }
 
-/**
- * Only for edge lines between areas.
- */
 void ED_screen_draw_edges(wmWindow *win)
 {
   bScreen *screen = WM_window_get_active_screen(win);
@@ -231,12 +228,6 @@ void ED_screen_draw_edges(wmWindow *win)
   }
 }
 
-/**
- * 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(ScrArea *sa1, ScrArea *sa2)
 {
   const eScreenDir dir = area_getorientation(sa1, sa2);
@@ -445,9 +436,6 @@ static void screen_preview_draw(const bScreen *screen, int size_x, int size_y)
   GPU_matrix_pop();
 }
 
-/**
- * Render the preview for a screen layout in \a screen.
- */
 void ED_screen_preview_render(const bScreen *screen, int size_x, int size_y, uint *r_rect)
 {
   char err_out[256] = "unknown";
diff --git a/source/blender/editors/screen/screen_edit.c b/source/blender/editors/screen/screen_edit.c
index 92151ea01b3..61d6997b0fb 100644
--- a/source/blender/editors/screen/screen_edit.c
+++ b/source/blender/editors/screen/screen_edit.c
@@ -203,9 +203,6 @@ ScrArea *area_split(const wmWindow *win,
   return newa;
 }
 
-/**
- * Empty screen, with 1 dummy area without spacedata. Uses window size.
- */
 bScreen *screen_add(Main *bmain, const char *name, const rcti *rect)
 {
   bScreen *screen = BKE_libblock_alloc(bmain, ID_SCR, name, 0);
@@ -274,9 +271,6 @@ 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)
 {
   screen_new->winid = win->winid;
@@ -284,11 +278,6 @@ void screen_new_activate_prepare(const wmWindow *win, bScreen *screen_new)
   screen_new->do_draw = true;
 }
 
-/**
- * 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)
 {
   if (sa_a == NULL || sa_b == NULL || sa_a == sa_b) {
@@ -329,9 +318,6 @@ eScreenDir area_getorientation(ScrArea *sa_a, ScrArea *sa_b)
   return -1;
 }
 
-/**
- * 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)
 {
@@ -536,13 +522,11 @@ static bool screen_area_join_ex(
   return true;
 }
 
-/* Join any two neighboring areas. Might involve complex changes. */
 int screen_area_join(bContext *C, bScreen *screen, ScrArea *sa1, ScrArea *sa2)
 {
   return screen_area_join_ex(C, screen, sa1, sa2, false);
 }
 
-/* Close a screen area, allowing most-aligned neighbor to take its place. */
 bool screen_area_close(struct bContext *C, bScreen *screen, ScrArea *area)
 {
   if (area == NULL) {
@@ -640,8 +624,6 @@ void ED_screen_do_listen(bContext *C, wmNotifier *note)
   }
 }
 
-/* make this screen usable */
-/* for file read and first use, for scaling window, area moves */
 void ED_screen_refresh(wmWindowManager *wm, wmWindow *win)
 {
   bScreen *screen = WM_window_get_active_screen(win);
@@ -681,7 +663,6 @@ void ED_screen_refresh(wmWindowManager *wm, wmWindow *win)
   screen->context = ed_screen_context;
 }
 
-/* file read, set all screens, ... */
 void ED_screens_init(Main *bmain, wmWindowManager *wm)
 {
   LISTBASE_FOREACH (wmWindow *, win, &wm->windows) {
@@ -709,10 +690,6 @@ void ED_screen_ensure_updated(wmWindowManager *wm, wmWindow *win, bScreen *scree
   }
 }
 
-/**
- * Utility to exit and free an area-region. Screen level regions (menus/popups) need to be treated
- * slightly differently, see #ui_region_temp_remove().
- */
 void ED_region_remove(bContext *C, ScrArea *area, ARegion *region)
 {
   ED_region_exit(C, region);
@@ -862,10 +839,6 @@ static void screen_cursor_set(wmWindow *win, const int xy[2])
   }
 }
 
-/**
- * Called in wm_event_system.c. sets state vars in screen, cursors.
- * event type is mouse move.
- */
 void ED_screen_set_active_region(bContext *C, wmWindow *win, const int xy[2])
 {
   bScreen *screen = WM_window_get_active_screen(win);
@@ -1126,10 +1099,6 @@ void ED_screen_global_areas_refresh(wmWindow *win)
 /* -------------------------------------------------------------------- */
 /* Screen changing */
 
-/**
- * \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, Main *bmain, bContext *C, wmWindow *win)
 {
@@ -1176,14 +1145,6 @@ void screen_change_update(bContext *C, wmWindow *win, bScreen *screen)
   WM_event_add_mousemove(win);
 }
 
-/**
- * \brief Change the active screen.
- *
- * Operator call, WM + Window + screen already existed before
- *
- * \warning Do NOT call in area/region queues!
- * \returns if screen changing was successful.
- */
 bool ED_screen_change(bContext *C, bScreen *screen)
 {
   Main *bmain = CTX_data_main(C);
@@ -1324,9 +1285,6 @@ ScrArea *ED_screen_full_newspace(bContext *C, ScrArea *area, int type)
   return newsa;
 }
 
-/**
- * \a was_prev_temp for the case previous space was a temporary fullscreen as well
- */
 void ED_screen_full_prevspace(bContext *C, ScrArea *area)
 {
   BLI_assert(area->full);
@@ -1356,7 +1314,6 @@ void ED_screen_restore_temp_type(bContext *C, ScrArea *area)
   }
 }
 
-/* restore a screen / area back to default operation, after temp fullscreen modes */
 void ED_screen_full_restore(bContext *C, ScrArea *area)
 {
   wmWindow *win = CTX_wm_window(C);
@@ -1463,28 +1420,11 @@ static bScreen *screen_state_to_nonnormal(bContext *C,
   return screen;
 }
 
-/**
- * Create a new temporary screen with a maximized, empty area.
- * This can be closed with #ED_screen_state_toggle().
- *
- * Use this to just create a new maximized screen/area, rather than maximizing an existing one.
- * Otherwise, maximize with #ED_screen_state_toggle().
- */
 bScreen *ED_screen_state_maximized_create(bContext *C)
 {
   return screen_state_to_nonnormal(C, CTX_wm_window(C), NULL, SCREENMAXIMIZED);
 }
 
-/**
- * This function toggles: if area is maximized/full then the parent will be restored.
- *
- * Use #ED_screen_state_maximized_create() if you do not want the toggle behavior when changing to
- * a maximized area. I.e. if you just want to open a new maximized screen/area, not maximize a
- * specific area. In the former case, space data of the maximized and non-maximized area should be
- * independent, in the latter it should be the same.
- *
- * \warning \a area may be freed.
- */
 ScrArea *ED_screen_state_toggle(bContext *C, wmWindow *win, ScrArea *area, const short state)
 {
   wmWindowManager *wm = CTX_wm_manager(C);
@@ -1592,14 +1532,6 @@ ScrArea *ED_screen_state_toggle(bContext *C, wmWindow *win, ScrArea *area, const
   return screen->areabase.first;
 }
 
-/**
- * Wrapper to open a temporary space either as fullscreen space, or as separate window, as defined
- * by \a display_type.
- *
- * \param title: Title to set for the window, if a window is spawned.
- * \param x, y: Position of the window, if a window is spawned.
- * \param sizex, sizey: Dimensions of the window, if a window is spawned.
- */
 ScrArea *ED_screen_temp_space_open(bContext *C,
                                    const char *title,
                                    int x,
@@ -1648,7 +1580,6 @@ ScrArea *ED_screen_temp_space_open(bContext *C,
   return area;
 }
 
-/* update frame rate info for viewport drawing */
 void ED_refresh_viewport_fps(bContext *C)
 {
   wmTimer *animtimer = CTX_wm_screen(C)->animtimer;
@@ -1674,9 +1605,6 @@ void ED_refresh_viewport_fps(bContext *C)
   }
 }
 
-/* redraws: uses defines from stime->redraws
- * enable: 1 - forward on, -1 - backwards on, 0 - off
- */
 void ED_screen_animation_timer(bContext *C, int redraws, int sync, int enable)
 {
   bScreen *screen = CTX_wm_screen(C);
@@ -1776,7 +1704,6 @@ void ED_screen_animation_timer_update(bScreen *screen, int redraws)
   }
 }
 
-/* results in fully updated anim system */
 void ED_update_for_newframe(Main *bmain, Depsgraph *depsgraph)
 {
   Scene *scene = DEG_get_input_scene(depsgraph);
@@ -1801,9 +1728,6 @@ void ED_update_for_newframe(Main *bmain, Depsgraph *depsgraph)
   BKE_scene_graph_update_for_newframe(depsgraph);
 }
 
-/*
- * return true if any active area requires to see in 3D
- */
 bool ED_screen_stereo3d_required(const bScreen *screen, const Scene *scene)
 {
   const bool is_multiview = (scene->r.scemode & R_MULTIVIEW) != 0;
diff --git a/source/blender/editors/screen/screen_geometry.c b/source/blender/editors/screen/screen_geometry.c
index e67c933cb8e..394a7fd7350 100644
--- a/source/blender/editors/screen/screen_geometry.c
+++ b/source/blender/editors/screen/screen_geometry.c
@@ -83,10 +83,6 @@ bool screen_geom_edge_is_horizontal(ScrEdge *se)
   return (se->v1->vec.y == se->v2->vec.y);
 }
 
-/**
- * \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 ScrAreaMap *area_map,
                                                   const rcti *bounds_rect,
                                                   const int mx,
@@ -124,7 +120,6 @@ ScrEdge *screen_geom_area_map_find_active_scredge(const ScrAreaMap *area_map,
   return NULL;
 }
 
-/* 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,
@@ -249,13 +244,6 @@ static bool screen_geom_vertices_scale_pass(const wmWindow *win,
   return needs_another_pass;
 }
 
-/**
- * \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)
 {
   rcti window_rect, screen_rect;
@@ -303,9 +291,6 @@ 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,
@@ -374,9 +359,6 @@ short screen_geom_find_area_split_point(const ScrArea *area,
   return x;
 }
 
-/**
- * Select all edges that are directly or indirectly connected to \a edge.
- */
 void screen_geom_select_connected_edge(const wmWindow *win, ScrEdge *edge)
 {
   bScreen *screen = WM_window_get_active_screen(win);
diff --git a/source/blender/editors/screen/screen_intern.h b/source/blender/editors/screen/screen_intern.h
index 47229e5e2b5..53d87005463 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 spacedata. 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);
diff --git a/source/blender/editors/screen/screen_ops.c b/source/blender/editors/screen/screen_ops.c
index 220697f465e..96012155a55 100644
--- a/source/blender/editors/screen/screen_ops.c
+++ b/source/blender/editors/screen/screen_ops.c
@@ -165,7 +165,6 @@ static bool ED_operator_screenactive_norender(bContext *C)
   return true;
 }
 
-/* when mouse is over area-edge */
 bool ED_operator_screen_mainwinactive(bContext *C)
 {
   if (CTX_wm_window(C) == NULL) {
@@ -219,10 +218,6 @@ bool ED_operator_objectmode(bContext *C)
   return true;
 }
 
-/**
- * Same as #ED_operator_objectmode() but additionally sets a "disabled hint". That is, a message
- * to be displayed to the user explaining why the operator can't be used in current context.
- */
 bool ED_operator_objectmode_poll_msg(bContext *C)
 {
   if (!ED_operator_objectmode(C)) {
@@ -257,7 +252,6 @@ bool ED_operator_region_view3d_active(bContext *C)
   return false;
 }
 
-/* generic for any view2d which uses anim_ops */
 bool ED_operator_animview_active(bContext *C)
 {
   if (ED_operator_areaactive(C)) {
@@ -289,21 +283,11 @@ bool ED_operator_outliner_active_no_editobject(bContext *C)
   return false;
 }
 
-/**
- * \note Will return true for file spaces in either file or asset browsing mode! See
- *       #ED_operator_file_browsing_active() (file browsing only) and
- *       #ED_operator_asset_browsing_active() (asset browsing only).
- */
 bool ED_operator_file_active(bContext *C)
 {
   return ed_spacetype_test(C, SPACE_FILE);
 }
 
-/**
- * \note Will only return true if the file space is in file browsing mode, not asset browsing! See
- *       #ED_operator_file_active() (file or asset browsing) and
- *       #ED_operator_asset_browsing_active() (asset browsing only).
- */
 bool ED_operator_file_browsing_active(bContext *C)
 {
   if (ed_spacetype_test(C, SPACE_FILE)) {
@@ -430,7 +414,6 @@ bool ED_operator_object_active_editable(bContext *C)
   return ED_operator_object_active_editable_ex(C, ob);
 }
 
-/** Object must be editable and fully local (i.e. not an override). */
 bool ED_operator_object_active_local_editable_ex(bContext *C, const Object *ob)
 {
   return ED_operator_object_active_editable_ex(C, ob) && !ID_IS_OVERRIDE_LIBRARY(ob);
@@ -530,7 +513,6 @@ bool ED_operator_posemode_exclusive(bContext *C)
   return ed_operator_posemode_exclusive_ex(C, obact);
 }
 
-/** Object must be editable, fully local (i.e. not an override), and exclusively in Pose mode. */
 bool ED_operator_object_active_local_editable_posemode_exclusive(bContext *C)
 {
   Object *obact = ED_object_active_context(C);
@@ -547,8 +529,6 @@ bool ED_operator_object_active_local_editable_posemode_exclusive(bContext *C)
   return true;
 }
 
-/* allows for pinned pose objects to be used in the object buttons
- * and the non-active pose object to be used in the 3D view */
 bool ED_operator_posemode_context(bContext *C)
 {
   Object *obpose = ED_pose_object_from_context(C);
@@ -588,7 +568,6 @@ bool ED_operator_posemode_local(bContext *C)
   return false;
 }
 
-/* wrapper for ED_space_image_show_uvedit */
 bool ED_operator_uvedit(bContext *C)
 {
   SpaceImage *sima = CTX_wm_space_image(C);
@@ -4812,7 +4791,6 @@ static void SCREEN_OT_animation_step(wmOperatorType *ot)
  * Animation Playback with Timer.
  * \{ */
 
-/* find window that owns the animation timer */
 bScreen *ED_screen_animation_playing(const wmWindowManager *wm)
 {
   LISTBASE_FOREACH (wmWindow *, win, &wm->windows) {
@@ -4839,7 +4817,6 @@ bScreen *ED_screen_animation_no_scrub(const wmWindowManager *wm)
   return NULL;
 }
 
-/* toggle operator */
 int ED_screen_animation_play(bContext *C, int sync, int mode)
 {
   bScreen *screen = CTX_wm_screen(C);
@@ -5391,9 +5368,6 @@ static void region_blend_end(bContext *C, ARegion *region, const bool is_running
   WM_event_remove_timer(CTX_wm_manager(C), NULL, region->regiontimer); /* frees rgi */
   region->regiontimer = NULL;
 }
-/**
- * \note Assumes that \a region itself is not a split version from previous region.
- */
 void ED_region_visibility_change_update_animated(bContext *C, ScrArea *area, ARegion *region)
 {
   wmWindowManager *wm = CTX_wm_manager(C);
@@ -5701,7 +5675,6 @@ static void SCREEN_OT_workspace_cycle(wmOperatorType *ot)
 /** \name Assigning Operator Types
  * \{ */
 
-/* called in spacetypes.c */
 void ED_operatortypes_screen(void)
 {
   /* Generic UI stuff. */
@@ -5791,7 +5764,6 @@ static void blend_file_drop_copy(wmDrag *drag, wmDropBox *drop)
   RNA_string_set(drop->ptr, "filepath", drag->path);
 }
 
-/* called in spacetypes.c */
 void ED_keymap_screen(wmKeyConfig *keyconf)
 {
   /* Screen Editing ------------------------------------------------ */
diff --git a/source/blender/editors/screen/workspace_edit.c b/source/blender/editors/screen/workspace_edit.c
index 4b81e713080..333a1fae99a 100644
--- a/source/blender/editors/screen/workspace_edit.c
+++ b/source/blender/editors/screen/workspace_edit.c
@@ -112,15 +112,6 @@ static WorkSpaceLayout *workspace_change_get_new_layout(Main *bmain,
       bmain, workspace_new, layout_new, layout_old, win);
 }
 
-/**
- * \brief Change the active workspace.
- *
- * Operator call, WM + Window + screen already existed before
- * Pretty similar to #ED_screen_change since changing workspace also changes screen.
- *
- * \warning Do NOT call in area/region queues!
- * \returns if workspace changing was successful.
- */
 bool ED_workspace_change(WorkSpace *workspace_new, bContext *C, wmWindowManager *wm, wmWindow *win)
 {
   Main *bmain = CTX_data_main(C);
@@ -160,10 +151,6 @@ bool ED_workspace_change(WorkSpace *workspace_new, bContext *C, wmWindowManager
   return true;
 }
 
-/**
- * Duplicate a workspace including its layouts. Does not activate the workspace, but
- * it stores the screen-layout to be activated (BKE_workspace_temp_layout_store)
- */
 WorkSpace *ED_workspace_duplicate(WorkSpace *workspace_old, Main *bmain, wmWindow *win)
 {
   WorkSpaceLayout *layout_active_old = BKE_workspace_active_layout_get(win->workspace_hook);
@@ -187,9 +174,6 @@ WorkSpace *ED_workspace_duplicate(WorkSpace *workspace_old, Main *bmain, wmWindo
   return workspace_new;
 }
 
-/**
- * \return if succeeded.
- */
 bool ED_workspace_delete(WorkSpace *workspace, Main *bmain, bContext *C, wmWindowManager *wm)
 {
   if (BLI_listbase_is_single(&bmain->workspaces)) {
@@ -220,10 +204,6 @@ bool ED_workspace_delete(WorkSpace *workspace, Main *bmain, bContext *C, wmWindo
   return true;
 }
 
-/**
- * Some editor data may need to be synced with scene data (3D View camera and layers).
- * This function ensures data is synced for editors in active layout of \a workspace.
- */
 void ED_workspace_scene_data_sync(WorkSpaceInstanceHook *hook, Scene *scene)
 {
   bScreen *screen = BKE_workspace_active_screen_get(hook);
diff --git a/source/blender/editors/screen/workspace_layout_edit.c b/source/blender/editors/screen/workspace_layout_edit.c
index 0ec32da0404..e34c4f96aa3 100644
--- a/source/blender/editors/screen/workspace_layout_edit.c
+++ b/source/blender/editors/screen/workspace_layout_edit.c
@@ -37,9 +37,6 @@
 
 #include "screen_intern.h"
 
-/**
- * Empty screen, with 1 dummy area without space-data. Uses window size.
- */
 WorkSpaceLayout *ED_workspace_layout_add(Main *bmain,
                                          WorkSpace *workspace,
                                          wmWindow *win,
@@ -129,10 +126,6 @@ static WorkSpaceLayout *workspace_layout_delete_find_new(const WorkSpaceLayout *
   return NULL;
 }
 
-/**
- * \warning Only call outside of area/region loops!
- * \return true if succeeded.
- */
 bool ED_workspace_layout_delete(WorkSpace *workspace, WorkSpaceLayout *layout_old, bContext *C)
 {
   const bScreen *screen_old = BKE_workspace_layout_screen_get(layout_old);
@@ -183,12 +176,6 @@ static bool screen_is_used_by_other_window(const wmWindow *win, const bScreen *s
   return BKE_screen_is_used(screen) && (screen->winid != win->winid);
 }
 
-/**
- * Make sure there is a non-fullscreen layout to switch to that is not used yet by an other window.
- * Needed for workspace or screen switching to ensure valid screens.
- *
- * \param layout_fallback_base: As last resort, this layout is duplicated and returned.
- */
 WorkSpaceLayout *ED_workspace_screen_change_ensure_unused_layout(
     Main *bmain,
     WorkSpace *workspace,