[Bf-blender-cvs] [3f6f89a06ba] master: Cleanup: move text.c comments to the struct/flag declarations

[Campbell Barton]

Commit: 3f6f89a06baeb12b64467c8e89d25295a62ed6b2
Author: Campbell Barton
Date:   Tue Jun 23 14:09:13 2020 +1000
Branches: master
https://developer.blender.org/rB3f6f89a06baeb12b64467c8e89d25295a62ed6b2

Cleanup: move text.c comments to the struct/flag declarations

Also update/correct some of the comments.

===================================================================

M	source/blender/blenkernel/intern/text.c
M	source/blender/editors/space_text/text_ops.c
M	source/blender/makesdna/DNA_space_types.h
M	source/blender/makesdna/DNA_text_types.h

===================================================================

diff --git a/source/blender/blenkernel/intern/text.c b/source/blender/blenkernel/intern/text.c
index fa827a8190c..f58c9fe2b69 100644
--- a/source/blender/blenkernel/intern/text.c
+++ b/source/blender/blenkernel/intern/text.c
@@ -59,34 +59,6 @@
 #  include "BPY_extern.h"
 #endif
 
-/*
- * How Texts should work
- * --
- * A text should relate to a file as follows -
- * (Text *)->filepath should be the place where the
- *     file will or has been saved.
- *
- * (Text *)->flags has the following bits
- *     TXT_ISDIRTY - should always be set if the file in mem. differs from
- *                     the file on disk, or if there is no file on disk.
- *     TXT_ISMEM - should always be set if the Text has not been mapped to
- *                     a file, in which case (Text *)->filepath may be NULL or garbage.
- *     TXT_ISEXT - should always be set if the Text is not to be written into
- *                     the .blend
- *     TXT_ISSCRIPT - should be set if the user has designated the text
- *                     as a script. (NEW: this was unused, but now it is needed by
- *                     space handler script links (see header_view3d.c, for example)
- *
- * ->>> see also: /makesdna/DNA_text_types.h
- *
- * Display
- * --
- *
- * The st->top determines at what line the top of the text is displayed.
- * If the user moves the cursor the st containing that cursor should
- * be popped ... other st's retain their own top location.
- */
-
 /* -------------------------------------------------------------------- */
 /** \name Prototypes
  * \{ */
@@ -737,6 +709,10 @@ bool txt_cursor_is_line_end(Text *text)
 
 /* -------------------------------------------------------------------- */
 /** \name Cursor Movement Functions
+ *
+ * \note If the user moves the cursor the space containing that cursor should be popped
+ * See #txt_pop_first, #txt_pop_last
+ * Other space-types retain their own top location.
  * \{ */
 
 void txt_move_up(Text *text, const bool sel)
@@ -1308,6 +1284,8 @@ void txt_sel_set(Text *text, int startl, int startc, int endl, int endc)
   text->selc = BLI_str_utf8_offset_from_index(tol->line, endc);
 }
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
 /** \name Buffer Conversion for Undo/Redo
  *
diff --git a/source/blender/editors/space_text/text_ops.c b/source/blender/editors/space_text/text_ops.c
index 670804d039e..e9e675ae226 100644
--- a/source/blender/editors/space_text/text_ops.c
+++ b/source/blender/editors/space_text/text_ops.c
@@ -543,10 +543,7 @@ static int text_make_internal_exec(bContext *C, wmOperator *UNUSED(op))
 
   text->flags |= TXT_ISMEM | TXT_ISDIRTY;
 
-  if (text->filepath) {
-    MEM_freeN(text->filepath);
-    text->filepath = NULL;
-  }
+  MEM_SAFE_FREE(text->filepath);
 
   text_update_cursor_moved(C);
   WM_event_add_notifier(C, NC_TEXT | NA_EDITED, text);
diff --git a/source/blender/makesdna/DNA_space_types.h b/source/blender/makesdna/DNA_space_types.h
index 31a8d967ccf..1cb42b333c7 100644
--- a/source/blender/makesdna/DNA_space_types.h
+++ b/source/blender/makesdna/DNA_space_types.h
@@ -1220,7 +1220,11 @@ typedef struct SpaceText {
 
   struct Text *text;
 
-  int top, left;
+  /** Determines at what line the top of the text is displayed. */
+  int top;
+
+  /** Determines the horizontal scroll (in columns). */
+  int left;
   char _pad1[4];
 
   short flags;
diff --git a/source/blender/makesdna/DNA_text_types.h b/source/blender/makesdna/DNA_text_types.h
index 40ab46aaf03..27663ffcbdd 100644
--- a/source/blender/makesdna/DNA_text_types.h
+++ b/source/blender/makesdna/DNA_text_types.h
@@ -43,7 +43,17 @@ typedef struct TextLine {
 typedef struct Text {
   ID id;
 
+  /**
+   * Optional file path, when NULL text is considered internal.
+   * Otherwise this path will be used when saving/reloading.
+   *
+   * When set this is where the file will or has been saved.
+   */
   char *filepath;
+
+  /**
+   * Python code object for this text (cached result of #Py_CompileStringObject).
+   */
   void *compiled;
 
   int flags;
@@ -58,12 +68,15 @@ typedef struct Text {
 
 #define TXT_TABSIZE 4
 
-/* text flags */
+/** #Text.flags */
 enum {
+  /** Set if the file in run-time differs from the file on disk, or if there is no file on disk. */
   TXT_ISDIRTY = 1 << 0,
+  /** When the text hasn't been written to a file. #Text.filepath may be NULL or invalid. */
   TXT_ISMEM = 1 << 2,
+  /** Should always be set if the Text is not to be written into the `.blend`. */
   TXT_ISEXT = 1 << 3,
-  /** Used by space handler scriptlinks. */
+  /** Load the script as a Python module when loading the `.blend` file. */
   TXT_ISSCRIPT = 1 << 4,
 
   TXT_FLAG_UNUSED_8 = 1 << 8, /* cleared */