From aa0d6cc7c76366fdcf96edf9acfc550bb6bc2a1f Mon Sep 17 00:00:00 2001 From: Allen Webster Date: Mon, 27 Feb 2017 00:57:21 -0500 Subject: [PATCH] filled in new documentation for markers API --- 4coder_API/types.h | 13 ++++++++++- 4coder_default_framework.h | 2 +- 4ed_api_implementation.cpp | 45 +++++++++++++++++++++++++++++++++----- 3 files changed, 52 insertions(+), 8 deletions(-) diff --git a/4coder_API/types.h b/4coder_API/types.h index 291f40fb..956e3ea5 100644 --- a/4coder_API/types.h +++ b/4coder_API/types.h @@ -608,12 +608,23 @@ STRUCT Buffer_Summary{ GLOBAL_VAR Buffer_Summary null_buffer_summary = {0}; +/* +DOC(A markers is a location in a buffer that, once placed, is effected by edits the same way characters are effected. In particular if an edit occurs in a location in the buffer before a marker, the marker is shifted forward or backward so that it remains on the same character.) +DOC_SEE(buffer_add_markers) +*/ STRUCT Marker{ + /* DOC(The current position of the marker measure in absolute byte positioning coordinates.) */ int32_t pos; + /* DOC(When a marker is inside a range that gets edited, by default the marker 'leans_left' which means it goes to the beginning of the edited range. If the field lean_right is set to true, the marker will lean right with edits and will go to the end of edited range.*/ bool32 lean_right; }; -typedef void* Marker_Handle; +/* +DOC(A handle to an internally held array of markers.) +DOC_SEE(Marker) +DOC_SEE(buffer_add_markers) +*/ +TYPEDEF void* Marker_Handle; STRUCT i32_Rect{ int32_t x0; diff --git a/4coder_default_framework.h b/4coder_default_framework.h index 91e4b4c4..c840049b 100644 --- a/4coder_default_framework.h +++ b/4coder_default_framework.h @@ -655,7 +655,7 @@ static char** get_current_code_extensions(int32_t *extension_count_out){ char **extension_list = default_extensions; int32_t extension_count = ArrayCount(default_extensions); - if (treat_as_code_exts.extensions != 0){ + if (treat_as_code_exts.extension_count != 0){ extension_list = treat_as_code_exts.extensions; extension_count = treat_as_code_exts.extension_count; } diff --git a/4ed_api_implementation.cpp b/4ed_api_implementation.cpp index 76394559..8e8a82d6 100644 --- a/4ed_api_implementation.cpp +++ b/4ed_api_implementation.cpp @@ -665,8 +665,7 @@ DOC_PARAM(str_len, This parameter specifies the length of the str string.) DOC_PARAM(edits, This parameter provides about the source string and destination range of each edit as an array.) DOC_PARAM(edit_count, This parameter specifies the number of Buffer_Edit structs in edits.) DOC_PARAM(type, This prameter specifies what type of batch edit to execute.) -DOC_RETURN(This call returns non-zero if the batch edit succeeds. This call can fail if the provided -buffer summary does not refer to an actual buffer in 4coder.) +DOC_RETURN(This call returns non-zero if the batch edit succeeds. This call can fail if the provided buffer summary does not refer to an actual buffer in 4coder.) DOC(TODO) DOC_SEE(Buffer_Edit) DOC_SEE(Buffer_Batch_Edit_Type) @@ -703,7 +702,14 @@ DOC_SEE(Buffer_Batch_Edit_Type) } API_EXPORT Marker_Handle -Buffer_Add_Markers(Application_Links *app, Buffer_Summary *buffer, uint32_t marker_count){ +Buffer_Add_Markers(Application_Links *app, Buffer_Summary *buffer, uint32_t marker_count) +/* +DOC_PARAM(buffer, The buffer on which to add the new markers.) +DOC_PARAM(marker_count, How many markers to be stored in the new marker array.) +DOC_RETURN(If this call succeeds it returns a handle to the new markers. If it fails it returns a null handle.) +DOC(This call makes an allocation of markers for the specified buffer. The newly allocated markers are not immediately activated. To activate a marker use buffer_set_markers to give the marker a value. The markers will remain allocated on the buffer until buffer_remove_markers is called or until the buffer is killed.) +DOC_SEE(Marker) +*/{ Command_Data *cmd = (Command_Data*)app->cmd_context; Models *models = cmd->models; Editing_File *file = imp_get_file(cmd, buffer); @@ -717,7 +723,17 @@ Buffer_Add_Markers(Application_Links *app, Buffer_Summary *buffer, uint32_t mark } API_EXPORT bool32 -Buffer_Set_Markers(Application_Links *app, Buffer_Summary *buffer, Marker_Handle marker, uint32_t first_marker_index, uint32_t marker_count, Marker *source_markers){ +Buffer_Set_Markers(Application_Links *app, Buffer_Summary *buffer, Marker_Handle marker, uint32_t first_marker_index, uint32_t marker_count, Marker *source_markers) +/* +DOC_PARAM(buffer, The buffer on which the specified markers are attached.) +DOC_PARAM(marker, The marker handle refering to the markers to be set.) +DOC_PARAM(first_marker_index, The index of the first marker to be set by this call.) +DOC_PARAM(marker_count, The number of markers to be set by this call.) +DOC_PARAM(source_markers, An array of marker_count Markers to specify the values to set to the markers specified.) +DOC_RETURN(On success returns non-zero, on failure returns zero.) +DOC(This call sets the value of a Marker, eliminating whatever value was there before. Any markers that are set become active if they were not active before. If a marker of lower index than first_marker_index was not active before this call, it will be cleared to zero and made active as well, so that all markers between 0 and first_marker_index + marker_count - 1 are active after this call. If first_marker_index + marker_count exceeds the originally allocated size of the marker array, this call will fail.) +DOC_SEE(Marker) +*/{ Command_Data *cmd = (Command_Data*)app->cmd_context; Editing_File *file = imp_get_file(cmd, buffer); @@ -732,7 +748,17 @@ Buffer_Set_Markers(Application_Links *app, Buffer_Summary *buffer, Marker_Handle } API_EXPORT bool32 -Buffer_Get_Markers(Application_Links *app, Buffer_Summary *buffer, Marker_Handle marker, uint32_t first_marker_index, uint32_t marker_count, Marker *markers_out){ +Buffer_Get_Markers(Application_Links *app, Buffer_Summary *buffer, Marker_Handle marker, uint32_t first_marker_index, uint32_t marker_count, Marker *markers_out) +/* +DOC_PARAM(buffer, The buffer on which the specified markers are attached.) +DOC_PARAM(marker, The marker handle refering to the markers to be read.) +DOC_PARAM(first_marker_index, The index of the first marker to be read by this call.) +DOC_PARAM(marker_count, The number of markers to be read by this call.) +DOC_PARAM(markers_out, An array of marker_count Markers to be filled by the result of the read.) +DOC_RETURN(On success returns non-zero, on failure returns zero.) +DOC(When the range specified by first_marker_index and marker_count is a range of active markers in the array specified by the marker handle, this call succeeds and fills the markers_out buffer with the current values of the specified markers.) +DOC_SEE(Marker) +*/{ Command_Data *cmd = (Command_Data*)app->cmd_context; Editing_File *file = imp_get_file(cmd, buffer); @@ -747,7 +773,14 @@ Buffer_Get_Markers(Application_Links *app, Buffer_Summary *buffer, Marker_Handle } API_EXPORT bool32 -Buffer_Remove_Markers(Application_Links *app, Buffer_Summary *buffer, Marker_Handle marker){ +Buffer_Remove_Markers(Application_Links *app, Buffer_Summary *buffer, Marker_Handle marker) +/* +DOC_PARAM(buffer, The buffer on which the specified markers are attached.) +DOC_PARAM(marker, The marker handle refering to the markers to be detached from the buffer.) +DOC_RETURN(On success returns non-zero, on failure returns zero.) +DOC(Deactivates the entire range of markers specified by the marker handle and frees the memory used to store the markers internally.) +DOC_SEE(buffer_add_markers) +*/{ Command_Data *cmd = (Command_Data*)app->cmd_context; Models *models = cmd->models; Editing_File *file = imp_get_file(cmd, buffer);