Cleanup: move text.c comments to the struct/flag declarations
authorCampbell Barton <ideasman42@gmail.com>
Tue, 23 Jun 2020 04:09:13 +0000 (14:09 +1000)
committerCampbell Barton <ideasman42@gmail.com>
Tue, 23 Jun 2020 04:09:13 +0000 (14:09 +1000)
Also update/correct some of the comments.

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

index fa827a8190c6d217a9f28b0e038f19dfe35157d5..f58c9fe2b691df83de0550323d1d1df6d60fdef3 100644 (file)
 #  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
  *
index 670804d039e4eb9602c4284cd13d8ea6e068f3d3..e9e675ae226a3125dbc3c3a25dde98418058ae8d 100644 (file)
@@ -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);
index 31a8d967ccfc8e33ae8a835257658012867b5311..1cb42b333c79eb88468b458a30f9ee94ea75466c 100644 (file)
@@ -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;
index 40ab46aaf03c74d3fbd6549fbf7a15b7ad7dd8e5..27663ffcbdd7035902386b409eb5447a46c90d4e 100644 (file)
@@ -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 */