From 74adc4782f6ec274d9097368b4d6c0f9259ec53d Mon Sep 17 00:00:00 2001 From: Allen Webster Date: Tue, 10 Dec 2019 10:46:12 -0800 Subject: [PATCH] Finished documentation, beginning to organize to acquire doc content at run time --- 4ed_api_implementation.cpp | 14 +- 4ed_app_target.cpp | 13 + .../4coder_doc_content_types.h | 24 +- custom/4coder_docs.cpp | 10 + custom/4coder_lists.cpp | 4 +- custom/4coder_profile.cpp | 1 + custom/4coder_profile_inspect.cpp | 3 +- custom/generated/command_metadata.h | 8 +- custom/generated/custom_api.h | 12 +- custom/generated/custom_api_master_list.h | 2 +- docs/4ed_doc_custom_api.cpp | 790 +-------------- docs/4ed_doc_custom_api_buffer.cpp | 95 +- docs/4ed_doc_custom_api_draw.cpp | 311 ++++++ docs/4ed_doc_custom_api_global.cpp | 944 ++++++++++++++++++ docs/4ed_doc_custom_api_main.cpp | 72 ++ docs/4ed_doc_helper.h | 31 + project.4coder | 2 +- 17 files changed, 1497 insertions(+), 839 deletions(-) rename docs/4ed_doc_content_types.h => custom/4coder_doc_content_types.h (86%) create mode 100644 custom/4coder_docs.cpp create mode 100644 docs/4ed_doc_custom_api_draw.cpp create mode 100644 docs/4ed_doc_custom_api_main.cpp create mode 100644 docs/4ed_doc_helper.h diff --git a/4ed_api_implementation.cpp b/4ed_api_implementation.cpp index 7cdad734..c2894a31 100644 --- a/4ed_api_implementation.cpp +++ b/4ed_api_implementation.cpp @@ -2718,13 +2718,12 @@ push_hot_directory(Application_Links *app, Arena *arena) return(push_string_copy(arena, hot->string)); } -api(custom) function b32 +api(custom) function void set_hot_directory(Application_Links *app, String_Const_u8 string) { Models *models = (Models*)app->cmd_context; Hot_Directory *hot = &models->hot_directory; hot_directory_set(hot, string); - return(true); } api(custom) function void @@ -2734,7 +2733,7 @@ send_exit_signal(Application_Links *app) models->keep_playing = false; } -api(custom) function b32 +api(custom) function void set_window_title(Application_Links *app, String_Const_u8 title) { Models *models = (Models*)app->cmd_context; @@ -2743,7 +2742,6 @@ set_window_title(Application_Links *app, String_Const_u8 title) umem copy_size = clamp_top(title.size, cap_before_null); block_copy(models->title_space, title.str, copy_size); models->title_space[copy_size] = 0; - return(true); } api(custom) function Vec2_f32 @@ -3071,4 +3069,12 @@ get_core_profile_list(Application_Links *app){ return(&models->profile_list); } +api(custom) function Doc_Cluster* +get_custom_layer_boundary_docs(Application_Links *app, Arena *arena){ + // TODO(allen): Need to be able to get the API_Definition of the custom + // layer boundary here. + API_Definition *api_def = 0; + return(doc_custom_api(arena, api_def)); +} + // BOTTOM diff --git a/4ed_app_target.cpp b/4ed_app_target.cpp index b37f9e09..463b38e8 100644 --- a/4ed_app_target.cpp +++ b/4ed_app_target.cpp @@ -58,6 +58,11 @@ #include "4ed_log.h" #include "4ed_app_models.h" +#include "generated/lexer_cpp.h" +#include "4ed_api_definition.h" +#include "4coder_doc_content_types.h" +#include "docs/4ed_doc_helper.h" + //////////////////////////////// #include "4coder_base_types.cpp" @@ -85,6 +90,14 @@ #define DYNAMIC_LINK_API #include "generated/font_api.cpp" +#include "4coder_token.cpp" +#include "generated/lexer_cpp.cpp" + +#include "4ed_api_definition.cpp" +#include "4ed_api_parser.cpp" +#include "docs/4ed_doc_content_types.cpp" +#include "docs/4ed_doc_custom_api.cpp" + #include "4ed_log.cpp" #include "4ed_coroutine.cpp" #include "4ed_mem.cpp" diff --git a/docs/4ed_doc_content_types.h b/custom/4coder_doc_content_types.h similarity index 86% rename from docs/4ed_doc_content_types.h rename to custom/4coder_doc_content_types.h index 17e0a809..dc40b305 100644 --- a/docs/4ed_doc_content_types.h +++ b/custom/4coder_doc_content_types.h @@ -1,11 +1,6 @@ /* - * Mr. 4th Dimention - Allen Webster - * - * 04.12.2019 - * - * Definition of information contained in 4coder documentation. - * - */ +4coder_doc_content_types.h - Documentation content types +*/ // TOP @@ -149,21 +144,6 @@ struct Doc_Cluster{ Doc_Log *last_log; }; -//////////////////////////////// - -struct Doc_Function{ - API_Call *call; - API_Param *param_iter; - Doc_Page *page; - Doc_Block *brief; - Doc_Block *sig; - Doc_Block *params; - Doc_Block *ret; - Doc_Block *det; - Doc_Block *examples; - Doc_Block *rel; -}; - #endif // BOTTOM diff --git a/custom/4coder_docs.cpp b/custom/4coder_docs.cpp new file mode 100644 index 00000000..fd0cbc1f --- /dev/null +++ b/custom/4coder_docs.cpp @@ -0,0 +1,10 @@ +/* +4coder_docs.cpp - Documentation explorers +*/ + +// TOP + + + +// BOTTOM + diff --git a/custom/4coder_lists.cpp b/custom/4coder_lists.cpp index dfed453a..16b3d824 100644 --- a/custom/4coder_lists.cpp +++ b/custom/4coder_lists.cpp @@ -1,6 +1,6 @@ /* -4coder_lists.cpp - List helpers and list commands -such as open file, switch buffer, or kill buffer. +4coder_lists.cpp - List helpers and list commands such as: +open file, switch buffer, or kill buffer. */ // TOP diff --git a/custom/4coder_profile.cpp b/custom/4coder_profile.cpp index 3437c77d..68bfff7c 100644 --- a/custom/4coder_profile.cpp +++ b/custom/4coder_profile.cpp @@ -8,6 +8,7 @@ function void profile_init(Profile_Global_List *list){ list->mutex = system_mutex_make(); list->node_arena = make_arena_system(KB(4)); + list->disable_bits = ProfileEnable_UserBit; } function Profile_Thread* diff --git a/custom/4coder_profile_inspect.cpp b/custom/4coder_profile_inspect.cpp index 752f9174..e36e220d 100644 --- a/custom/4coder_profile_inspect.cpp +++ b/custom/4coder_profile_inspect.cpp @@ -147,8 +147,7 @@ profile_parse(Arena *arena, Profile_Global_List *src){ // to get the root range. Range_u64 time_range = {max_u64, 0}; insp_thread->root.thread = insp_thread; - profile_parse_record(arena, &result, &insp_thread->root, node->first_record, - &time_range); + profile_parse_record(arena, &result, &insp_thread->root, node->first_record, &time_range); insp_thread->root.time = time_range; insp_thread->root.closed = true; diff --git a/custom/generated/command_metadata.h b/custom/generated/command_metadata.h index 679feefb..4b9e5da1 100644 --- a/custom/generated/command_metadata.h +++ b/custom/generated/command_metadata.h @@ -249,9 +249,9 @@ i32 line_number; }; static Command_Metadata fcoder_metacmd_table[226] = { { PROC_LINKS(default_view_input_handler, 0), false, "default_view_input_handler", 26, "Input consumption loop for default view behavior", 48, "w:\\4ed\\code\\custom\\4coder_default_hooks.cpp", 43, 56 }, -{ PROC_LINKS(profile_enable, 0), false, "profile_enable", 14, "Allow 4coder's self profiler to gather new profiling information.", 65, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 211 }, -{ PROC_LINKS(profile_disable, 0), false, "profile_disable", 15, "Prevent 4coder's self profiler from gathering new profiling information.", 72, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 218 }, -{ PROC_LINKS(profile_clear, 0), false, "profile_clear", 13, "Clear all profiling information from 4coder's self profiler.", 60, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 225 }, +{ PROC_LINKS(profile_enable, 0), false, "profile_enable", 14, "Allow 4coder's self profiler to gather new profiling information.", 65, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 212 }, +{ PROC_LINKS(profile_disable, 0), false, "profile_disable", 15, "Prevent 4coder's self profiler from gathering new profiling information.", 72, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 219 }, +{ PROC_LINKS(profile_clear, 0), false, "profile_clear", 13, "Clear all profiling information from 4coder's self profiler.", 60, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 226 }, { PROC_LINKS(seek_beginning_of_textual_line, 0), false, "seek_beginning_of_textual_line", 30, "Seeks the cursor to the beginning of the line across all text.", 62, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2160 }, { PROC_LINKS(seek_end_of_textual_line, 0), false, "seek_end_of_textual_line", 24, "Seeks the cursor to the end of the line across all text.", 56, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2166 }, { PROC_LINKS(seek_beginning_of_line, 0), false, "seek_beginning_of_line", 22, "Seeks the cursor to the beginning of the visual line.", 53, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2172 }, @@ -467,7 +467,7 @@ static Command_Metadata fcoder_metacmd_table[226] = { { PROC_LINKS(miblo_decrement_time_stamp, 0), false, "miblo_decrement_time_stamp", 26, "Decrement a time stamp under the cursor by one second. (format [m]m:ss or h:mm:ss", 81, "w:\\4ed\\code\\custom\\4coder_miblo_numbers.cpp", 43, 237 }, { PROC_LINKS(miblo_increment_time_stamp_minute, 0), false, "miblo_increment_time_stamp_minute", 33, "Increment a time stamp under the cursor by one minute. (format [m]m:ss or h:mm:ss", 81, "w:\\4ed\\code\\custom\\4coder_miblo_numbers.cpp", 43, 243 }, { PROC_LINKS(miblo_decrement_time_stamp_minute, 0), false, "miblo_decrement_time_stamp_minute", 33, "Decrement a time stamp under the cursor by one minute. (format [m]m:ss or h:mm:ss", 81, "w:\\4ed\\code\\custom\\4coder_miblo_numbers.cpp", 43, 249 }, -{ PROC_LINKS(profile_inspect, 0), true, "profile_inspect", 15, "Inspect all currently collected profiling information in 4coder's self profiler.", 80, "w:\\4ed\\code\\custom\\4coder_profile_inspect.cpp", 45, 887 }, +{ PROC_LINKS(profile_inspect, 0), true, "profile_inspect", 15, "Inspect all currently collected profiling information in 4coder's self profiler.", 80, "w:\\4ed\\code\\custom\\4coder_profile_inspect.cpp", 45, 886 }, { PROC_LINKS(kill_tutorial, 0), false, "kill_tutorial", 13, "If there is an active tutorial, kill it.", 40, "w:\\4ed\\code\\custom\\4coder_tutorial.cpp", 38, 9 }, { PROC_LINKS(tutorial_maximize, 0), false, "tutorial_maximize", 17, "Expand the tutorial window", 26, "w:\\4ed\\code\\custom\\4coder_tutorial.cpp", 38, 20 }, { PROC_LINKS(tutorial_minimize, 0), false, "tutorial_minimize", 17, "Shrink the tutorial window", 26, "w:\\4ed\\code\\custom\\4coder_tutorial.cpp", 38, 34 }, diff --git a/custom/generated/custom_api.h b/custom/generated/custom_api.h index 65fb2316..b691475b 100644 --- a/custom/generated/custom_api.h +++ b/custom/generated/custom_api.h @@ -150,9 +150,9 @@ #define custom_try_modify_face_sig() b32 custom_try_modify_face(Application_Links* app, Face_ID id, Face_Description* description) #define custom_try_release_face_sig() b32 custom_try_release_face(Application_Links* app, Face_ID id, Face_ID replacement_id) #define custom_push_hot_directory_sig() String_Const_u8 custom_push_hot_directory(Application_Links* app, Arena* arena) -#define custom_set_hot_directory_sig() b32 custom_set_hot_directory(Application_Links* app, String_Const_u8 string) +#define custom_set_hot_directory_sig() void custom_set_hot_directory(Application_Links* app, String_Const_u8 string) #define custom_send_exit_signal_sig() void custom_send_exit_signal(Application_Links* app) -#define custom_set_window_title_sig() b32 custom_set_window_title(Application_Links* app, String_Const_u8 title) +#define custom_set_window_title_sig() void custom_set_window_title(Application_Links* app, String_Const_u8 title) #define custom_draw_string_oriented_sig() Vec2_f32 custom_draw_string_oriented(Application_Links* app, Face_ID font_id, ARGB_Color color, String_Const_u8 str, Vec2_f32 point, u32 flags, Vec2_f32 delta) #define custom_get_string_advance_sig() f32 custom_get_string_advance(Application_Links* app, Face_ID font_id, String_Const_u8 str) #define custom_draw_rectangle_sig() void custom_draw_rectangle(Application_Links* app, Rect_f32 rect, f32 roundness, ARGB_Color color) @@ -323,9 +323,9 @@ typedef Face_ID custom_try_create_new_face_type(Application_Links* app, Face_Des typedef b32 custom_try_modify_face_type(Application_Links* app, Face_ID id, Face_Description* description); typedef b32 custom_try_release_face_type(Application_Links* app, Face_ID id, Face_ID replacement_id); typedef String_Const_u8 custom_push_hot_directory_type(Application_Links* app, Arena* arena); -typedef b32 custom_set_hot_directory_type(Application_Links* app, String_Const_u8 string); +typedef void custom_set_hot_directory_type(Application_Links* app, String_Const_u8 string); typedef void custom_send_exit_signal_type(Application_Links* app); -typedef b32 custom_set_window_title_type(Application_Links* app, String_Const_u8 title); +typedef void custom_set_window_title_type(Application_Links* app, String_Const_u8 title); typedef Vec2_f32 custom_draw_string_oriented_type(Application_Links* app, Face_ID font_id, ARGB_Color color, String_Const_u8 str, Vec2_f32 point, u32 flags, Vec2_f32 delta); typedef f32 custom_get_string_advance_type(Application_Links* app, Face_ID font_id, String_Const_u8 str); typedef void custom_draw_rectangle_type(Application_Links* app, Rect_f32 rect, f32 roundness, ARGB_Color color); @@ -672,9 +672,9 @@ internal Face_ID try_create_new_face(Application_Links* app, Face_Description* d internal b32 try_modify_face(Application_Links* app, Face_ID id, Face_Description* description); internal b32 try_release_face(Application_Links* app, Face_ID id, Face_ID replacement_id); internal String_Const_u8 push_hot_directory(Application_Links* app, Arena* arena); -internal b32 set_hot_directory(Application_Links* app, String_Const_u8 string); +internal void set_hot_directory(Application_Links* app, String_Const_u8 string); internal void send_exit_signal(Application_Links* app); -internal b32 set_window_title(Application_Links* app, String_Const_u8 title); +internal void set_window_title(Application_Links* app, String_Const_u8 title); internal Vec2_f32 draw_string_oriented(Application_Links* app, Face_ID font_id, ARGB_Color color, String_Const_u8 str, Vec2_f32 point, u32 flags, Vec2_f32 delta); internal f32 get_string_advance(Application_Links* app, Face_ID font_id, String_Const_u8 str); internal void draw_rectangle(Application_Links* app, Rect_f32 rect, f32 roundness, ARGB_Color color); diff --git a/custom/generated/custom_api_master_list.h b/custom/generated/custom_api_master_list.h index 0536ebf9..4b4a62d3 100644 --- a/custom/generated/custom_api_master_list.h +++ b/custom/generated/custom_api_master_list.h @@ -150,7 +150,7 @@ api(custom) function Face_ID try_create_new_face(Application_Links* app, Face_De api(custom) function b32 try_modify_face(Application_Links* app, Face_ID id, Face_Description* description); api(custom) function b32 try_release_face(Application_Links* app, Face_ID id, Face_ID replacement_id); api(custom) function String_Const_u8 push_hot_directory(Application_Links* app, Arena* arena); -api(custom) function b32 set_hot_directory(Application_Links* app, String_Const_u8 string); +api(custom) function void set_hot_directory(Application_Links* app, String_Const_u8 string); api(custom) function void send_exit_signal(Application_Links* app); api(custom) function b32 set_window_title(Application_Links* app, String_Const_u8 title); api(custom) function Vec2_f32 draw_string_oriented(Application_Links* app, Face_ID font_id, ARGB_Color color, String_Const_u8 str, Vec2_f32 point, u32 flags, Vec2_f32 delta); diff --git a/docs/4ed_doc_custom_api.cpp b/docs/4ed_doc_custom_api.cpp index c6cb7441..5fd32686 100644 --- a/docs/4ed_doc_custom_api.cpp +++ b/docs/4ed_doc_custom_api.cpp @@ -9,814 +9,28 @@ // TOP -#include "4coder_base_types.h" -#include "4coder_token.h" -#include "generated/lexer_cpp.h" -#include "../4ed_api_definition.h" -#include "4ed_doc_content_types.h" - -#include "4coder_base_types.cpp" -#include "4coder_stringf.cpp" -#include "4coder_malloc_allocator.cpp" -#include "4coder_token.cpp" -#include "generated/lexer_cpp.cpp" -#include "../4ed_api_definition.cpp" -#include "../4ed_api_parser.cpp" -#include "4ed_doc_content_types.cpp" -#include "4coder_file.cpp" - function void doc_custom_app_ptr(Arena *arena, Doc_Function *func){ doc_function_param(arena, func, "app"); doc_text(arena, func->params, "the standard custom layer context pointer"); } -//////////////////////////////// - #include "4ed_doc_custom_api_global.cpp" #include "4ed_doc_custom_api_buffer.cpp" #include "4ed_doc_custom_api_view.cpp" - -//////////////////////////////// +#include "4ed_doc_custom_api_draw.cpp" function Doc_Cluster* doc_custom_api(Arena *arena, API_Definition *api_def){ Doc_Cluster *cluster = new_doc_cluster(arena, "Custom Layer Boundary API", "custom api"); - Doc_Function func = {}; - doc_custom_api__global(arena, api_def, cluster); doc_custom_api__buffer(arena, api_def, cluster); doc_custom_api__view(arena, api_def, cluster); - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "create_user_managed_scope", &func)){ - doc_function_brief(arena, &func, "Create a managed scope that is not tied to anything in the core and that the user can destroy"); - - // params - doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the new managed scope's id"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "destroy_user_managed_scope", &func)){ - doc_function_brief(arena, &func, "Destroy a managed scope that was previously created by the user"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "scope"); - doc_text(arena, params, "the id of the managed scope to destroy"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "non-zero if the scope exists, zero otherwise"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "get_global_managed_scope", &func)){ - doc_function_brief(arena, &func, "Get the id of the 'global' managed scope"); - - // params - doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the id of the global managed scope"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "The global managed scope has a lifetime tied to the instance of 4coder itself. It is unique in that it does not combine with other scopes to create unique intersection scopes. To put it another way, all scopes are automatically implicitly dependent on the global scope, so adding it to the list of scopes in a 'multiple dependencies' scope has no effect on the result."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "get_managed_scope_with_multiple_dependencies", &func)){ - doc_function_brief(arena, &func, "Get a scope that has a lifetime dependent on all of the dependent scopes and is unique up to set isomorphisms of the 'hard' dependencies"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "scopes"); - doc_text(arena, params, "a pointer at the base of an array of scope ids specifying the set of dependencies to use in querying or constructing the resulting scope"); - - doc_function_param(arena, &func, "count"); - doc_text(arena, params, "the number of scope ids in the scopes array"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the scope id of the scope with multiple dependencies on success, when all the scopes in input array exist, zero otherwise"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "The behavior of this call can be confusing so here are some rules of thumb for how it works, assuming all input scopes are valid:"); - doc_paragraph(arena, det); - doc_text(arena, det, "1. When there is only one scope in the parameters, that scope is the result. {A} -> A;"); - doc_paragraph(arena, det); - doc_text(arena, det, "2. When there are two or more parameters that are the same scope, the result is the that scope again. {A, A, ...} -> A;"); - doc_paragraph(arena, det); - doc_text(arena, det, "3. When any scope in the parameters is the special global scope, it is as if it is not there. {A, G} -> A"); - doc_paragraph(arena, det); - doc_text(arena, det, "4. When two scopes are constructed from the same set of parameters, they are the same, regardless of parameter order. {A, B} -> C; {B, A} -> C;"); - doc_paragraph(arena, det); - doc_text(arena, det, "5. When any of the scopes in the parameters was itself returned by this call, it is as if the parameters from it's constructor are substituted for it. {A, B} -> C; {C, D} -> E; {A, B, D} -> E;"); - doc_paragraph(arena, det); - doc_text(arena, det, "6. When the parameter set is empty the result is the global scope. {} -> G"); - doc_paragraph(arena, det); - doc_text(arena, det, "For a set-theoretic definition one can think of scopes as being keyed by a set of 'atoms'. Getting the key for a scope with multiple dependencies is defined by the operation of union of sets of atoms. The global scope is keyed by the empty set. A scope continues to exist as long all the atoms in it's key set exist."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_scope_clear_contents", &func)){ - doc_function_brief(arena, &func, "Clear everything allocated inside a given scope without destroying the scope itself"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "scope"); - doc_text(arena, params, "the id of the scope to clear"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "non-zero if the scope exists, zero otherwise"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_scope_clear_self_all_dependent_scopes", &func)){ - doc_function_brief(arena, &func, "Clear everything allocated inside an atomic scope and all of it's dependent scopes without destroying any of them"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "scope"); - doc_text(arena, params, "the id of the scope to modify"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "non-zero if the scope exists and is atomic, zero otherwise"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "A scope is atomic when it uniquely tied to a specified entity or when it is directly created by the user. By the set-theoretic definition of scopes, a scope is atomic when it's key contains only one atom."); - doc_paragraph(arena, det); - doc_text(arena, det, "A scope is atomic specifically whenever it satisfies any of these conditions:"); - doc_paragraph(arena, det); - doc_text(arena, det, "1. It is a scope tied to a buffer and returned by buffer_get_managed_scope"); - doc_paragraph(arena, det); - doc_text(arena, det, "2. It is a scope tied to a view and returned by view_get_managed_scope"); - doc_paragraph(arena, det); - doc_text(arena, det, "3. It was created by a call to create_user_managed_scope"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_scope_allocator", &func)){ - doc_function_brief(arena, &func, "Get the base allocator for a managed scope"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "scope"); - doc_text(arena, params, "the id of the scope to query"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "a pointer to the base allocator for the managed scope if it exists, zero otherwise"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "Anything allocated by this base allocator exists only as long as the managed scope exists. All of the allocations in the managed scope are freed by a bulk free operation when the managed scopes life time ends."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_id_group_highest_id", &func)){ - doc_function_brief(arena, &func, "Get the highest id issued for a particular group of managed ids"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "group"); - doc_text(arena, params, "a name identifying a managed id group"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the highest id returned by managed_id_declare for the given group, zero if the group has never been used to declare an id"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_id_declare", &func)){ - doc_function_brief(arena, &func, "Get a unique id for a given name within a particular group"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "group"); - doc_text(arena, params, "a name identifying a managed id group"); - - doc_function_param(arena, &func, "name"); - doc_text(arena, params, "a name identifying a managed id"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the id assigned to the given (group, name) pair"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "When this is called for the first time for a given group, the first id returned is 1, subsequent calls with new names for an existing group return the next highest id, calls for (group, name) pairs that have already been assigned an id return the same id again. The upshot of this is that managed ids can be used to essentially create run-time allocated co-operative enums, where the group names the enum, and the names are the elements of the enum."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_id_get", &func)){ - doc_function_brief(arena, &func, "Like managed_id_declare except never returns new ids, only ids that have already been declared."); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "group"); - doc_text(arena, params, "a name identifying a managed id group"); - - doc_function_param(arena, &func, "name"); - doc_text(arena, params, "a name identifying a managed id"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the id assigned to the given (group, name) pair"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "managed_id_declare"); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, ""); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_scope_get_attachment", &func)){ - doc_function_brief(arena, &func, "Get an attachment contained to a managed scope, allocating it if necessary"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "scope"); - doc_text(arena, params, "the id of a scope to query"); - - doc_function_param(arena, &func, "id"); - doc_text(arena, params, "the id of the attachment to query"); - - doc_function_param(arena, &func, "size"); - doc_text(arena, params, "the expected size for the attachment, used to allocate memory when the attachment did not previously exist, used to check that the attachment is at least as large as expected if it already exists"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "a pointer to the base of the attachment when the scope exists and no error ocurred in checking the size of the attachment, zero otherwise"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "Attachments are allocated on a scopes base allocator, and thus are only valid for as long as the scope itself is valid. Whe in doubt, re-query for an attachment and recheck that the pointer returned is non-zero, as often calls between one usage and another can have an effect on the location or existence of an attachment."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_scope_attachment_erase", &func)){ - doc_function_brief(arena, &func, "Free an attachment on a managed scope"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "scope"); - doc_text(arena, params, "the id of the scope to modify"); - - doc_function_param(arena, &func, "id"); - doc_text(arena, params, "the id of the attachment to modify"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "non-zero when the scope exists, zero otherwise"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "alloc_buffer_markers_on_buffer", &func)){ - doc_function_brief(arena, &func, "Allocate buffer markers inside a managed scope and attach them to a buffer"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "buffer_id"); - doc_text(arena, params, "the buffer on which them markers will be attached"); - - doc_function_param(arena, &func, "count"); - doc_text(arena, params, "the number of markers to allocate"); - - doc_function_param(arena, &func, "optional_extra_scope"); - doc_text(arena, params, "either a null pointer, or a pointer to a managed scope"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "on success, when the buffer exists, and the optional_extra_scope is valid, a new managed object id, otherwise zero"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "By default, markers are allocated in the scope of the buffer they are attached to, this is how their lifetime is tied to the lifetime of the buffer. When an additional scope is supplied, it is combined with the buffer's scope via the same joining operation used in get_managed_scope_with_multiple_dependencies and the markers are allocated in that scope instead."); - doc_paragraph(arena, det); - doc_text(arena, det, "Markers are updated by edits to the buffer to which they are attached, so that they the same position in the buffer even as text is shifted around by edit operations. This can be used, for instance, to track the locations of compilation errors even as some compilation errors have already been fixed and shifted the position of later errors."); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, "get_managed_scope_with_multiple_dependencies"); - doc_function_add_related(arena, rel, "Marker"); - } - - //////////////////////////////// - - // TODO(allen): Remove alloc_managed_memory_in_scope - if (begin_doc_call(arena, cluster, api_def, "alloc_managed_memory_in_scope", &func)){ - doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_object_get_item_size", &func)){ - doc_function_brief(arena, &func, "Get the size of the items in a managed object"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "object"); - doc_text(arena, params, "the id of the managed object to query"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "on success, when the object exists, the number of bytes in each item of the managed object, otherwise zero"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns the size of the items in the array."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_object_get_item_count", &func)){ - doc_function_brief(arena, &func, "Get the number of the items in a managed object"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "object"); - doc_text(arena, params, "the id of the managed object to query"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "on success, when the object exists, the number of items in the managed object, otherwise zero"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns the number of items in the array."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_object_get_pointer", &func)){ - doc_function_brief(arena, &func, "Get a pointer to he base of a managed object"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "object"); - doc_text(arena, params, "the id of the managed object to query"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "on success, when the object exists, a pointer to the base of the memory allocated for the object, otherwise zero"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns a pointer to base of the array. Careful! This pointer is a pointer to memory tied to a managed scope, so it can lose validity if the scope closes, and modifications to the memory at this pointer will be reflected throughout all systems relying on it."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_object_get_type", &func)){ - doc_function_brief(arena, &func, "Get a type code indicating what sort data is represented by a managed object"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "object"); - doc_text(arena, params, "the id of the object to query"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "on success, when the object exists, the type code of the object, zero otherwise"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_object_get_containing_scope", &func)){ - doc_function_brief(arena, &func, "Get the id of the scope that contains a particular managed object"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "object"); - doc_text(arena, params, "the id of a managed object"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "on success, when the object exists, the id of the managed scope that contains the object, otherwise zero"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "managed_object_free", &func)){ - doc_function_brief(arena, &func, "Destroy a managed object, free it's memory back to the scope containing it, and detach it from whatever associations it has in the core"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "object"); - doc_text(arena, params, "the id of the object to free"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "non-zero when the object exists, otherwise zero"); - } - - //////////////////////////////// - - // TODO(allen): remove managed_object_store_data - if (begin_doc_call(arena, cluster, api_def, "managed_object_store_data", &func)){ - doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); - } - - //////////////////////////////// - - // TODO(allen): remove managed_object_load_data - if (begin_doc_call(arena, cluster, api_def, "managed_object_load_data", &func)){ - doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "get_next_input", &func)){ - doc_function_brief(arena, &func, "In a view context, yield control to the core until new input is sent to this view, then return that input"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "get_properties"); - doc_text(arena, params, "flags for properties of an event that should be allowed to be returned from this call"); - - doc_function_param(arena, &func, "abort_properties"); - doc_text(arena, params, "flags for properties of an event that should be converted into abort events before returning from this call"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the next input that is sent to this view context, or cleared to zero if this is not a view context thread"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "This works as a blocking call on it's thread, blocking until the core has more input. However it only works in view context threads. View context threads are created by the core whenever a view is created, and has the primary responsibility of dispatching user input and other events. The base of view context threads is determined by HookID_ViewEventHandler."); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, "User_Input"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "get_current_input_sequence_number", &func)){ - doc_function_brief(arena, &func, "In a view context, get the sequence number for the input that has been most recently sent to the view"); - - // params - doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the sequence number of the most recent input sent to the view, or zero if this is not a view context thread"); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, "get_next_input"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "get_current_input", &func)){ - doc_function_brief(arena, &func, "In a view context, get the input that has been most recently sent to the view"); - - // params - doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the most recent input sent to the view; cleared to zero if this is not called from a view context thread, or if no inputs have been sent to this view context thread yet"); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, "get_next_input"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "set_current_input", &func)){ - doc_function_brief(arena, &func, "Modify the memory of the event that was most recently sent to the calling view context memory"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "input"); - doc_text(arena, params, "a pointer to the input struct to copy over the existing input struct in the core"); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "This call only has the effect of altering the result of future calls to get_current_input until the next time input is sent to the calling view context thread. There is no effect when called from threads that are not view contexts."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "leave_current_input_unhandled", &func)){ - doc_function_brief(arena, &func, "Notifies the core that the input currently being handled by a view context thread should be treated as if it were not handled"); - - // params - doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, "When events are handled, future handlers for them are skipped. This is especially important because text input is passed as a seperate event after key stroke events, and if a key stroke event is marked as handled, then the text event that would have been generated by the key stroke is skipped."); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "set_custom_hook", &func)){ - doc_function_brief(arena, &func, "Modify the a global hook binding"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "hook_id"); - doc_text(arena, params, "the id of the hook to be modified"); - - doc_function_param(arena, &func, "func_ptr"); - doc_text(arena, params, "a pointer to the hook function, the function pointer must have a specific signature to match the hook_id's expected signature, but this call does not do the type checking for this, so watch out for that"); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, "Hook_ID"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "set_custom_hook_memory_size", &func)){ - doc_function_brief(arena, &func, "Set the memory size for the extra memory used to store the state of certain hooks"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "hook_id"); - doc_text(arena, params, "the id of the hook to be modified"); - - doc_function_param(arena, &func, "size"); - doc_text(arena, params, "the size in bytes of the memory set aside for the state of the specified hook"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "non-zero when the hook id is valid and accepts extra memory size, otherwise zero"); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, "view_current_context_hook_memory"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "get_mouse_state", &func)){ - doc_function_brief(arena, &func, "Get the state of the mouse as of this frame"); - - // params - doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the current mouse state struct"); - } - - //////////////////////////////// - - // TODO(allen): remove get_active_query_bars - if (begin_doc_call(arena, cluster, api_def, "get_active_query_bars", &func)){ - doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); - } - - //////////////////////////////// - - // TODO(allen): remove start_query_bar - if (begin_doc_call(arena, cluster, api_def, "start_query_bar", &func)){ - doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); - } - - //////////////////////////////// - - // TODO(allen): remove end_query_bar - if (begin_doc_call(arena, cluster, api_def, "end_query_bar", &func)){ - doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); - } - - //////////////////////////////// - - // TODO(allen): remove clear_all_query_bars - if (begin_doc_call(arena, cluster, api_def, "clear_all_query_bars", &func)){ - doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "print_message", &func)){ - doc_function_brief(arena, &func, "Print a message to the *messages* buffer"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "message"); - doc_text(arena, params, "the string to write to the *messages* buffer"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "log_string", &func)){ - doc_function_brief(arena, &func, "Write a string to the *log* buffer"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "str"); - doc_text(arena, params, "the string to write to the log"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "non-zero when the string was written to the log, each thread can individually have logging disabled, in which case zero is returned"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "get_largest_face_id", &func)){ - doc_function_brief(arena, &func, "Get the largest face id that is currently assigned to a face"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "the largest face id that is currently assigned to a face"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "set_global_face", &func)){ - doc_function_brief(arena, &func, "Change the global default face"); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, "id"); - doc_text(arena, params, "the id of the new global default face"); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, "non-zero on success, when the face exists, otherwise zero"); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "", &func)){ - doc_function_brief(arena, &func, ""); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, ""); - doc_text(arena, params, ""); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, ""); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, ""); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, ""); - } - - //////////////////////////////// - - if (begin_doc_call(arena, cluster, api_def, "", &func)){ - doc_function_brief(arena, &func, ""); - - // params - Doc_Block *params = doc_function_begin_params(arena, &func); - doc_custom_app_ptr(arena, &func); - - doc_function_param(arena, &func, ""); - doc_text(arena, params, ""); - - // return - Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, ""); - - // details - Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, ""); - - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, ""); - } + doc_custom_api__draw(arena, api_def, cluster); return(cluster); } -#include -int main(void){ - Arena arena = make_arena_malloc(); - - String_Const_u8 me = string_u8_litexpr(__FILE__); - String_Const_u8 docs_folder = string_remove_last_folder(me); - String_Const_u8 root = string_remove_last_folder(docs_folder); - String_Const_u8 file_name = push_u8_stringf(&arena, "%.*scustom/generated/custom_api_master_list.h", - string_expand(root)); - - FILE *file = fopen((char*)file_name.str, "rb"); - if (file == 0){ - printf("could not load %s\n", file_name.str); - return(1); - } - - printf("documenting %s\n", file_name.str); - String_Const_u8 text = file_load_all(&arena, file); - fclose(file); - - API_Definition_List def_list = {}; - api_parse_source_add_to_list(&arena, file_name, text, &def_list); - - API_Definition *api_def = api_get_api(&def_list, string_u8_litexpr("custom")); - Doc_Cluster *cluster = doc_custom_api(&arena, api_def); - - for (Doc_Log *node = cluster->first_log; - node != 0; - node = node->next){ - printf("%.*s\n", string_expand(node->content)); - } - - return(0); -} - // BOTTOM diff --git a/docs/4ed_doc_custom_api_buffer.cpp b/docs/4ed_doc_custom_api_buffer.cpp index 1450d9d6..a9fac64f 100644 --- a/docs/4ed_doc_custom_api_buffer.cpp +++ b/docs/4ed_doc_custom_api_buffer.cpp @@ -1005,27 +1005,104 @@ doc_custom_api__buffer(Arena *arena, API_Definition *api_def, Doc_Cluster *clust //////////////////////////////// - if (begin_doc_call(arena, cluster, api_def, "", &func)){ - doc_function_brief(arena, &func, ""); + if (begin_doc_call(arena, cluster, api_def, "buffer_history_merge_record_range", &func)){ + doc_function_brief(arena, &func, "Merge a range of records into a single group record"); // params Doc_Block *params = doc_function_begin_params(arena, &func); doc_custom_app_ptr(arena, &func); - doc_function_param(arena, &func, ""); - doc_text(arena, params, ""); + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to modify"); + + doc_function_param(arena, &func, "first_index"); + doc_text(arena, params, "the first index in the range to merge"); + + doc_function_param(arena, &func, "last_index"); + doc_text(arena, params, "the last index in the range to merge, forming an inclusive-inclusive range"); + + doc_function_param(arena, &func, "flags"); + doc_text(arena, params, "flags controlling the behavior of the operation"); // return Doc_Block *ret = doc_function_return(arena, &func); - doc_text(arena, ret, ""); + doc_text(arena, ret, "non-zero on success, when the buffer exists, and the index range is contained within the buffer history, otherwise zero"); // details Doc_Block *det = doc_function_details(arena, &func); - doc_text(arena, det, ""); + doc_text(arena, det, "Group records contain all the same information that the range of individual records previously contained. A group is treated as a single unit in undo-redo operations."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_history_clear_after_current_state", &func)){ + doc_function_brief(arena, &func, "Forget the portion of the buffer history on the redo side"); - // related - Doc_Block *rel = doc_function_begin_related(arena, &func); - doc_function_add_related(arena, rel, ""); + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to modify"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_set_face", &func)){ + doc_function_brief(arena, &func, "Change the face of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to modify"); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the face to set on the buffer"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer and face exist, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_find_all_matches", &func)){ + doc_function_brief(arena, &func, "Find all matches for a search pattern in a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "arena"); + doc_text(arena, params, "the arena on which the returned string will be allocated"); + + doc_function_param(arena, &func, "buffer"); + doc_text(arena, params, "the id of the buffer to search"); + + doc_function_param(arena, &func, "string_id"); + doc_text(arena, params, "the id to store into the resulting string matches"); + + doc_function_param(arena, &func, "range"); + doc_text(arena, params, "the range in byte positions where all matches must be contained"); + + doc_function_param(arena, &func, "needle"); + doc_text(arena, params, "the string to search for in the buffer range"); + + doc_function_param(arena, &func, "predicate"); + doc_text(arena, params, "a character predicate used to check the left and right side of the match to add left sloppy and right sloppy match flags."); + + doc_function_param(arena, &func, "direction"); + doc_text(arena, params, "the direction of the scan through the buffer range determining the order of the generated matches"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a linked list of matches to the search pattern"); } } diff --git a/docs/4ed_doc_custom_api_draw.cpp b/docs/4ed_doc_custom_api_draw.cpp new file mode 100644 index 00000000..4f44227f --- /dev/null +++ b/docs/4ed_doc_custom_api_draw.cpp @@ -0,0 +1,311 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 09.12.2019 + * + * Documentation of the custom layer's primary api : buffer-related calls + * + */ + +// TOP + +function void +doc_custom_api__draw(Arena *arena, API_Definition *api_def, Doc_Cluster *cluster){ + Doc_Function func = {}; + + if (begin_doc_call(arena, cluster, api_def, "draw_string_oriented", &func)){ + doc_function_brief(arena, &func, "Directly render text"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "font_id"); + doc_text(arena, params, "the id of the face to use rendering the text"); + + doc_function_param(arena, &func, "color"); + doc_text(arena, params, "the color of the text"); + + doc_function_param(arena, &func, "str"); + doc_text(arena, params, "the text to be rendered"); + + doc_function_param(arena, &func, "point"); + doc_text(arena, params, "the position of the text, in pixels relative to the screen's top left corner"); + + doc_function_param(arena, &func, "flags"); + doc_text(arena, params, "flags determining the orientation of the string to render"); + + doc_function_param(arena, &func, "delta"); + doc_text(arena, params, "a unit vector specifying the direction along which the text advances"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the new point after advancing the point while laying out the text"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "As a render function, this only takes effect during a call to the render hook."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_string_advance", &func)){ + doc_function_brief(arena, &func, "Compute the total advance of a string rendered in a particular font"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "font_id"); + doc_text(arena, params, "the id of the face to use rendering the text"); + + doc_function_param(arena, &func, "str"); + doc_text(arena, params, "the text to be rendered"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the total advance of the string"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "draw_rectangle", &func)){ + doc_function_brief(arena, &func, "Directly render a rectangle"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "rect"); + doc_text(arena, params, "the rectangle coordinates, in pixels relative to the top left corner of the screen"); + + doc_function_param(arena, &func, "roundness"); + doc_text(arena, params, "the roundness of the pixels, set as a radius of a circular curve measured in pixels"); + + doc_function_param(arena, &func, "color"); + doc_text(arena, params, "the color of the rectangle"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "As a render function, this only takes effect during a call to the render hook."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "draw_rectangle_outline", &func)){ + doc_function_brief(arena, &func, "Directly render a rectangle outline"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "rect"); + doc_text(arena, params, "the rectangle coordinates, in pixels relative to the top left corner of the screen"); + + doc_function_param(arena, &func, "roundness"); + doc_text(arena, params, "the roundness of the pixels, set as a radius of a circular curve measured in pixels"); + + doc_function_param(arena, &func, "thickness"); + doc_text(arena, params, "the thickness, in pixels, of the rectangle outline"); + + doc_function_param(arena, &func, "color"); + doc_text(arena, params, "the color of the rectangle"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "As a render function, this only takes effect during a call to the render hook."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "draw_set_clip", &func)){ + doc_function_brief(arena, &func, "Set the clip rectangle for future render functions"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "new_clip"); + doc_text(arena, params, "the new rectangular coordinates of the clip rectangle, in pixels relative to the top left corner of the screen"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the previous value of clip rectangle"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "As a render function, this only takes effect during a call to the render hook."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "text_layout_create", &func)){ + doc_function_brief(arena, &func, "Create a text layout object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to read for layout"); + + doc_function_param(arena, &func, "rect"); + doc_text(arena, params, "the region on the screen where the layout will be placed"); + + doc_function_param(arena, &func, "buffer_point"); + doc_text(arena, params, "the point in the buffer that will be placed in the top left corner of the rectangle"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the new text layout object, when the buffer exists and contains the buffer point, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "text_layout_region", &func)){ + doc_function_brief(arena, &func, "Get the on screen rectangular region of a layout object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "text_layout_id"); + doc_text(arena, params, "the id of the text layout object"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the text layout object exists, the rectangular region used to create the object, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "text_layout_get_buffer", &func)){ + doc_function_brief(arena, &func, "Get the buffer of a layout object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "text_layout_id"); + doc_text(arena, params, "the id of the text layout object"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the text layout object exists, the id of the buffer used to create the object, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "text_layout_get_visible_range", &func)){ + doc_function_brief(arena, &func, "Get the range in byte positions within the buffer that are visible in a text layout"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "text_layout_id"); + doc_text(arena, params, "the id of the text layout object"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the text layout object exists, the range of positions in the buffer that are visible in the object, otherwise cleared to zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "text_layout_line_on_screen", &func)){ + doc_function_brief(arena, &func, "Get the range of the y-axis spanned by a line layout"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "layout_id"); + doc_text(arena, params, "the id of the text layout object"); + + doc_function_param(arena, &func, "line_number"); + doc_text(arena, params, "the line number of the line to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists and the line is visible in the layout, the range in pixels from the top to the bottom of a particular line, cleared to zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "text_layout_character_on_screen", &func)){ + doc_function_brief(arena, &func, "Get the rectangle covered by a character in the layout"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "layout_id"); + doc_text(arena, params, "the id of the text layout object"); + + doc_function_param(arena, &func, "pos"); + doc_text(arena, params, "the byte position to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists and the position is visible in the layout, the rectangle in pixels covered by the character, cleared to zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "paint_text_color", &func)){ + doc_function_brief(arena, &func, "Set the color of a range of characters in a text layout"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "layout_id"); + doc_text(arena, params, "the id of the text layout object"); + + doc_function_param(arena, &func, "range"); + doc_text(arena, params, "the range in byte positions to modify"); + + doc_function_param(arena, &func, "color"); + doc_text(arena, params, "the new color of the text in the range"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "text_layout_free", &func)){ + doc_function_brief(arena, &func, "Release the resources associated with a text layout object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "text_layout_id"); + doc_text(arena, params, "the id of the text layout object"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the text layout object exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "draw_text_layout", &func)){ + doc_function_brief(arena, &func, "Directly render a text layout object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "layout_id"); + doc_text(arena, params, "the id of the text layout object"); + + doc_function_param(arena, &func, "special_color"); + doc_text(arena, params, "the color to use for characters with the special character flag"); + + doc_function_param(arena, &func, "ghost_color"); + doc_text(arena, params, "the color to use for characters with the ghost character flag"); + } +} + +// BOTTOM + diff --git a/docs/4ed_doc_custom_api_global.cpp b/docs/4ed_doc_custom_api_global.cpp index 5ec02b5b..db1b735d 100644 --- a/docs/4ed_doc_custom_api_global.cpp +++ b/docs/4ed_doc_custom_api_global.cpp @@ -269,6 +269,950 @@ doc_custom_api__global(Arena *arena, API_Definition *api_def, Doc_Cluster *clust Doc_Block *det = doc_function_details(arena, &func); doc_text(arena, det, "All virtual events are triggered after all directly enqueued commands, before the next real event, and before the current frame renders."); } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "create_user_managed_scope", &func)){ + doc_function_brief(arena, &func, "Create a managed scope that is not tied to anything in the core and that the user can destroy"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the new managed scope's id"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "destroy_user_managed_scope", &func)){ + doc_function_brief(arena, &func, "Destroy a managed scope that was previously created by the user"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the managed scope to destroy"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the scope exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_global_managed_scope", &func)){ + doc_function_brief(arena, &func, "Get the id of the 'global' managed scope"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the global managed scope"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The global managed scope has a lifetime tied to the instance of 4coder itself. It is unique in that it does not combine with other scopes to create unique intersection scopes. To put it another way, all scopes are automatically implicitly dependent on the global scope, so adding it to the list of scopes in a 'multiple dependencies' scope has no effect on the result."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_managed_scope_with_multiple_dependencies", &func)){ + doc_function_brief(arena, &func, "Get a scope that has a lifetime dependent on all of the dependent scopes and is unique up to set isomorphisms of the 'hard' dependencies"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scopes"); + doc_text(arena, params, "a pointer at the base of an array of scope ids specifying the set of dependencies to use in querying or constructing the resulting scope"); + + doc_function_param(arena, &func, "count"); + doc_text(arena, params, "the number of scope ids in the scopes array"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the scope id of the scope with multiple dependencies on success, when all the scopes in input array exist, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The behavior of this call can be confusing so here are some rules of thumb for how it works, assuming all input scopes are valid:"); + doc_paragraph(arena, det); + doc_text(arena, det, "1. When there is only one scope in the parameters, that scope is the result. {A} -> A;"); + doc_paragraph(arena, det); + doc_text(arena, det, "2. When there are two or more parameters that are the same scope, the result is the that scope again. {A, A, ...} -> A;"); + doc_paragraph(arena, det); + doc_text(arena, det, "3. When any scope in the parameters is the special global scope, it is as if it is not there. {A, G} -> A"); + doc_paragraph(arena, det); + doc_text(arena, det, "4. When two scopes are constructed from the same set of parameters, they are the same, regardless of parameter order. {A, B} -> C; {B, A} -> C;"); + doc_paragraph(arena, det); + doc_text(arena, det, "5. When any of the scopes in the parameters was itself returned by this call, it is as if the parameters from it's constructor are substituted for it. {A, B} -> C; {C, D} -> E; {A, B, D} -> E;"); + doc_paragraph(arena, det); + doc_text(arena, det, "6. When the parameter set is empty the result is the global scope. {} -> G"); + doc_paragraph(arena, det); + doc_text(arena, det, "For a set-theoretic definition one can think of scopes as being keyed by a set of 'atoms'. Getting the key for a scope with multiple dependencies is defined by the operation of union of sets of atoms. The global scope is keyed by the empty set. A scope continues to exist as long all the atoms in it's key set exist."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_clear_contents", &func)){ + doc_function_brief(arena, &func, "Clear everything allocated inside a given scope without destroying the scope itself"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the scope to clear"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the scope exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_clear_self_all_dependent_scopes", &func)){ + doc_function_brief(arena, &func, "Clear everything allocated inside an atomic scope and all of it's dependent scopes without destroying any of them"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the scope to modify"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the scope exists and is atomic, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "A scope is atomic when it uniquely tied to a specified entity or when it is directly created by the user. By the set-theoretic definition of scopes, a scope is atomic when it's key contains only one atom."); + doc_paragraph(arena, det); + doc_text(arena, det, "A scope is atomic specifically whenever it satisfies any of these conditions:"); + doc_paragraph(arena, det); + doc_text(arena, det, "1. It is a scope tied to a buffer and returned by buffer_get_managed_scope"); + doc_paragraph(arena, det); + doc_text(arena, det, "2. It is a scope tied to a view and returned by view_get_managed_scope"); + doc_paragraph(arena, det); + doc_text(arena, det, "3. It was created by a call to create_user_managed_scope"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_allocator", &func)){ + doc_function_brief(arena, &func, "Get the base allocator for a managed scope"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the scope to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a pointer to the base allocator for the managed scope if it exists, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Anything allocated by this base allocator exists only as long as the managed scope exists. All of the allocations in the managed scope are freed by a bulk free operation when the managed scopes life time ends."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_id_group_highest_id", &func)){ + doc_function_brief(arena, &func, "Get the highest id issued for a particular group of managed ids"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "group"); + doc_text(arena, params, "a name identifying a managed id group"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the highest id returned by managed_id_declare for the given group, zero if the group has never been used to declare an id"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_id_declare", &func)){ + doc_function_brief(arena, &func, "Get a unique id for a given name within a particular group"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "group"); + doc_text(arena, params, "a name identifying a managed id group"); + + doc_function_param(arena, &func, "name"); + doc_text(arena, params, "a name identifying a managed id"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id assigned to the given (group, name) pair"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When this is called for the first time for a given group, the first id returned is 1, subsequent calls with new names for an existing group return the next highest id, calls for (group, name) pairs that have already been assigned an id return the same id again. The upshot of this is that managed ids can be used to essentially create run-time allocated co-operative enums, where the group names the enum, and the names are the elements of the enum."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_id_get", &func)){ + doc_function_brief(arena, &func, "Like managed_id_declare except never returns new ids, only ids that have already been declared."); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "group"); + doc_text(arena, params, "a name identifying a managed id group"); + + doc_function_param(arena, &func, "name"); + doc_text(arena, params, "a name identifying a managed id"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id assigned to the given (group, name) pair"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "managed_id_declare"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, ""); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_get_attachment", &func)){ + doc_function_brief(arena, &func, "Get an attachment contained to a managed scope, allocating it if necessary"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of a scope to query"); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the attachment to query"); + + doc_function_param(arena, &func, "size"); + doc_text(arena, params, "the expected size for the attachment, used to allocate memory when the attachment did not previously exist, used to check that the attachment is at least as large as expected if it already exists"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a pointer to the base of the attachment when the scope exists and no error ocurred in checking the size of the attachment, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Attachments are allocated on a scopes base allocator, and thus are only valid for as long as the scope itself is valid. Whe in doubt, re-query for an attachment and recheck that the pointer returned is non-zero, as often calls between one usage and another can have an effect on the location or existence of an attachment."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_attachment_erase", &func)){ + doc_function_brief(arena, &func, "Free an attachment on a managed scope"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the scope to modify"); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the attachment to modify"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the scope exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "alloc_buffer_markers_on_buffer", &func)){ + doc_function_brief(arena, &func, "Allocate buffer markers inside a managed scope and attach them to a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the buffer on which them markers will be attached"); + + doc_function_param(arena, &func, "count"); + doc_text(arena, params, "the number of markers to allocate"); + + doc_function_param(arena, &func, "optional_extra_scope"); + doc_text(arena, params, "either a null pointer, or a pointer to a managed scope"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the buffer exists, and the optional_extra_scope is valid, a new managed object id, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "By default, markers are allocated in the scope of the buffer they are attached to, this is how their lifetime is tied to the lifetime of the buffer. When an additional scope is supplied, it is combined with the buffer's scope via the same joining operation used in get_managed_scope_with_multiple_dependencies and the markers are allocated in that scope instead."); + doc_paragraph(arena, det); + doc_text(arena, det, "Markers are updated by edits to the buffer to which they are attached, so that they the same position in the buffer even as text is shifted around by edit operations. This can be used, for instance, to track the locations of compilation errors even as some compilation errors have already been fixed and shifted the position of later errors."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "get_managed_scope_with_multiple_dependencies"); + doc_function_add_related(arena, rel, "Marker"); + } + + //////////////////////////////// + + // TODO(allen): Remove alloc_managed_memory_in_scope + if (begin_doc_call(arena, cluster, api_def, "alloc_managed_memory_in_scope", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_item_size", &func)){ + doc_function_brief(arena, &func, "Get the size of the items in a managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the managed object to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, the number of bytes in each item of the managed object, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns the size of the items in the array."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_item_count", &func)){ + doc_function_brief(arena, &func, "Get the number of the items in a managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the managed object to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, the number of items in the managed object, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns the number of items in the array."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_pointer", &func)){ + doc_function_brief(arena, &func, "Get a pointer to he base of a managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the managed object to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, a pointer to the base of the memory allocated for the object, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns a pointer to base of the array. Careful! This pointer is a pointer to memory tied to a managed scope, so it can lose validity if the scope closes, and modifications to the memory at this pointer will be reflected throughout all systems relying on it."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_type", &func)){ + doc_function_brief(arena, &func, "Get a type code indicating what sort data is represented by a managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the object to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, the type code of the object, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_containing_scope", &func)){ + doc_function_brief(arena, &func, "Get the id of the scope that contains a particular managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of a managed object"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, the id of the managed scope that contains the object, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_free", &func)){ + doc_function_brief(arena, &func, "Destroy a managed object, free it's memory back to the scope containing it, and detach it from whatever associations it has in the core"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the object to free"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the object exists, otherwise zero"); + } + + //////////////////////////////// + + // TODO(allen): remove managed_object_store_data + if (begin_doc_call(arena, cluster, api_def, "managed_object_store_data", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): remove managed_object_load_data + if (begin_doc_call(arena, cluster, api_def, "managed_object_load_data", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_next_input", &func)){ + doc_function_brief(arena, &func, "In a view context, yield control to the core until new input is sent to this view, then return that input"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "get_properties"); + doc_text(arena, params, "flags for properties of an event that should be allowed to be returned from this call"); + + doc_function_param(arena, &func, "abort_properties"); + doc_text(arena, params, "flags for properties of an event that should be converted into abort events before returning from this call"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the next input that is sent to this view context, or cleared to zero if this is not a view context thread"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "This works as a blocking call on it's thread, blocking until the core has more input. However it only works in view context threads. View context threads are created by the core whenever a view is created, and has the primary responsibility of dispatching user input and other events. The base of view context threads is determined by HookID_ViewEventHandler."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "User_Input"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_current_input_sequence_number", &func)){ + doc_function_brief(arena, &func, "In a view context, get the sequence number for the input that has been most recently sent to the view"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the sequence number of the most recent input sent to the view, or zero if this is not a view context thread"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "get_next_input"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_current_input", &func)){ + doc_function_brief(arena, &func, "In a view context, get the input that has been most recently sent to the view"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the most recent input sent to the view; cleared to zero if this is not called from a view context thread, or if no inputs have been sent to this view context thread yet"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "get_next_input"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_current_input", &func)){ + doc_function_brief(arena, &func, "Modify the memory of the event that was most recently sent to the calling view context memory"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "input"); + doc_text(arena, params, "a pointer to the input struct to copy over the existing input struct in the core"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "This call only has the effect of altering the result of future calls to get_current_input until the next time input is sent to the calling view context thread. There is no effect when called from threads that are not view contexts."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "leave_current_input_unhandled", &func)){ + doc_function_brief(arena, &func, "Notifies the core that the input currently being handled by a view context thread should be treated as if it were not handled"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When events are handled, future handlers for them are skipped. This is especially important because text input is passed as a seperate event after key stroke events, and if a key stroke event is marked as handled, then the text event that would have been generated by the key stroke is skipped."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_custom_hook", &func)){ + doc_function_brief(arena, &func, "Modify the a global hook binding"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "hook_id"); + doc_text(arena, params, "the id of the hook to be modified"); + + doc_function_param(arena, &func, "func_ptr"); + doc_text(arena, params, "a pointer to the hook function, the function pointer must have a specific signature to match the hook_id's expected signature, but this call does not do the type checking for this, so watch out for that"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Hook_ID"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_custom_hook_memory_size", &func)){ + doc_function_brief(arena, &func, "Set the memory size for the extra memory used to store the state of certain hooks"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "hook_id"); + doc_text(arena, params, "the id of the hook to be modified"); + + doc_function_param(arena, &func, "size"); + doc_text(arena, params, "the size in bytes of the memory set aside for the state of the specified hook"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the hook id is valid and accepts extra memory size, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "view_current_context_hook_memory"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_mouse_state", &func)){ + doc_function_brief(arena, &func, "Get the state of the mouse as of this frame"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the current mouse state struct"); + } + + //////////////////////////////// + + // TODO(allen): remove get_active_query_bars + if (begin_doc_call(arena, cluster, api_def, "get_active_query_bars", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): remove start_query_bar + if (begin_doc_call(arena, cluster, api_def, "start_query_bar", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): remove end_query_bar + if (begin_doc_call(arena, cluster, api_def, "end_query_bar", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): remove clear_all_query_bars + if (begin_doc_call(arena, cluster, api_def, "clear_all_query_bars", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "print_message", &func)){ + doc_function_brief(arena, &func, "Print a message to the *messages* buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "message"); + doc_text(arena, params, "the string to write to the *messages* buffer"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "log_string", &func)){ + doc_function_brief(arena, &func, "Write a string to the *log* buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "str"); + doc_text(arena, params, "the string to write to the log"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the string was written to the log, each thread can individually have logging disabled, in which case zero is returned"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_largest_face_id", &func)){ + doc_function_brief(arena, &func, "Get the largest face id that is currently assigned to a face"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the largest face id that is currently assigned to a face"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_global_face", &func)){ + doc_function_brief(arena, &func, "Change the global default face"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the new global default face"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the face exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "global_history_edit_group_begin", &func)){ + doc_function_brief(arena, &func, "Begin an edit group to merge all edits across all buffers"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When inside a global history edit group, all edits are merged into group edits, and the global edit number counter is frozen. Groups are formed by a nest counter, so that each call to global_history_edit_group_begin must be matched by a call to global_history_edit_group_end."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "global_history_edit_group_end", &func)){ + doc_function_brief(arena, &func, "End an edit group to merge all edits across all buffers"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When inside a global history edit group, all edits are merged into group edits, and the global edit number counter is frozen. Groups are formed by a nest counter, so that each call to global_history_edit_group_begin must be matched by a call to global_history_edit_group_end."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_face_description", &func)){ + doc_function_brief(arena, &func, "Get the description of a face"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the id of the face to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the description of the given face on success, when the face exists, otherwise cleared to zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "A face description contains the parameters to initializing a face."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Face_Description"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_face_metrics", &func)){ + doc_function_brief(arena, &func, "Get the metrics of a face"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the id of the face to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the metrics of the given face on success, when the face exists, otherwise cleared to zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Face_Metrics"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_face_advance_map", &func)){ + doc_function_brief(arena, &func, "Get the advance map of a face"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the id of the face to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the advance map of the given face on success, when the face exists, otherwise cleared to zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Face_Advance_Map"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_face_id", &func)){ + doc_function_brief(arena, &func, "Get the id of a face attached to a buffer, or of the global face"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query, or zero to query for the global face"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the queried face, if the buffer exists or if the query is for the global face, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "try_create_new_face", &func)){ + doc_function_brief(arena, &func, "Attempt to create a new face given a face description"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "description"); + doc_text(arena, params, "the description of the new face"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the new face on success, when it is possible to instantiate the face, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Face_Description"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "try_modify_face", &func)){ + doc_function_brief(arena, &func, "Attempt to modify a face given a face description"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the face to modify"); + + doc_function_param(arena, &func, "description"); + doc_text(arena, params, "the description to use to reinstantiate the face"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the face already exists and the new instantiation is possible, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Face_Description"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "try_release_face", &func)){ + doc_function_brief(arena, &func, "Attempt to release the resources tied up in a face"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the face to release"); + + doc_function_param(arena, &func, "replacement_id"); + doc_text(arena, params, "the id of the new face to replace existing usages of the released face"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the face exists and the replacement also exists and is a different face, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "push_hot_directory", &func)){ + doc_function_brief(arena, &func, "Get a copy of the hot directory"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "arena"); + doc_text(arena, params, "the arena on which the returned string will be allocated"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a copy of the hot directory"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_hot_directory", &func)){ + doc_function_brief(arena, &func, "Set the hot directory"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "string"); + doc_text(arena, params, "the new value of the hot directory"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "send_exit_signal", &func)){ + doc_function_brief(arena, &func, "Send the signal to the core to try to shutdown"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The exit signal does not automatically close 4coder, first the exit hook is called, which can cancel the exit. If it does not cancel the exit, then 4coder closes."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_window_title", &func)){ + doc_function_brief(arena, &func, "Set the title of the 4coder window"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "title"); + doc_text(arena, params, "the new title of the window"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "open_color_picker", &func)){ + doc_function_brief(arena, &func, "Potentially going to be deprecated - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "animate_in_n_milliseconds", &func)){ + doc_function_brief(arena, &func, "Set a wakeup timer to run a 4coder update tick and render"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "n"); + doc_text(arena, params, "the number of milliseconds roughly approximating how long to wait until sending a wakeup signal, the wakeup is always delayed by a minimum of a 16 milliseconds"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Without an animate timer set, 4coder only wakes up when events are sent to it. When there is an animation timer, 4coder wakes up when the animation timer triggers a timer event."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_core_profile_list", &func)){ + doc_function_brief(arena, &func, "Potentially going to be deprecated - do not rely on this call!"); + } } // BOTTOM diff --git a/docs/4ed_doc_custom_api_main.cpp b/docs/4ed_doc_custom_api_main.cpp new file mode 100644 index 00000000..744d6ea0 --- /dev/null +++ b/docs/4ed_doc_custom_api_main.cpp @@ -0,0 +1,72 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 10.12.2019 + * + * Documentation of the custom layer's primary api. + * + */ + +// TOP + +#include "4coder_base_types.h" +#include "4coder_token.h" +#include "generated/lexer_cpp.h" +#include "../4ed_api_definition.h" +#include "4coder_doc_content_types.h" +#include "4ed_doc_helper.h" + +#include "4coder_base_types.cpp" +#include "4coder_stringf.cpp" +#include "4coder_malloc_allocator.cpp" +#include "4coder_token.cpp" +#include "generated/lexer_cpp.cpp" +#include "../4ed_api_definition.cpp" +#include "../4ed_api_parser.cpp" +#include "4ed_doc_content_types.cpp" +#include "4coder_file.cpp" + +//////////////////////////////// + +#include "4ed_doc_custom_api.cpp" + +//////////////////////////////// + +#include + +int main(void){ + Arena arena = make_arena_malloc(); + + String_Const_u8 me = string_u8_litexpr(__FILE__); + String_Const_u8 docs_folder = string_remove_last_folder(me); + String_Const_u8 root = string_remove_last_folder(docs_folder); + String_Const_u8 file_name = push_u8_stringf(&arena, "%.*scustom/generated/custom_api_master_list.h", + string_expand(root)); + + FILE *file = fopen((char*)file_name.str, "rb"); + if (file == 0){ + printf("could not load %s\n", file_name.str); + return(1); + } + + printf("documenting %s\n", file_name.str); + String_Const_u8 text = file_load_all(&arena, file); + fclose(file); + + API_Definition_List def_list = {}; + api_parse_source_add_to_list(&arena, file_name, text, &def_list); + + API_Definition *api_def = api_get_api(&def_list, string_u8_litexpr("custom")); + Doc_Cluster *cluster = doc_custom_api(&arena, api_def); + + for (Doc_Log *node = cluster->first_log; + node != 0; + node = node->next){ + printf("%.*s\n", string_expand(node->content)); + } + + return(0); +} + +// BOTTOM + diff --git a/docs/4ed_doc_helper.h b/docs/4ed_doc_helper.h new file mode 100644 index 00000000..3a789f23 --- /dev/null +++ b/docs/4ed_doc_helper.h @@ -0,0 +1,31 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 04.12.2019 + * + * Definition of information contained in 4coder documentation. + * + */ + +// TOP + +#if !defined(FRED_DOC_HELPER_H) +#define FRED_DOC_HELPER_H + +struct Doc_Function{ + API_Call *call; + API_Param *param_iter; + Doc_Page *page; + Doc_Block *brief; + Doc_Block *sig; + Doc_Block *params; + Doc_Block *ret; + Doc_Block *det; + Doc_Block *examples; + Doc_Block *rel; +}; + +#endif + +// BOTTOM + diff --git a/project.4coder b/project.4coder index c9cea3ad..26ad9930 100644 --- a/project.4coder +++ b/project.4coder @@ -45,7 +45,7 @@ command_list = { { .name = "build custom api docs", .out = "*compilation*", .footer_panel = true, .save_dirty_files = true, - .cmd = { { "custom\\bin\\build_one_time docs\\4ed_doc_custom_api.cpp ..\\build", .os = "win" }, }, }, + .cmd = { { "custom\\bin\\build_one_time docs\\4ed_doc_custom_api_main.cpp ..\\build", .os = "win" }, }, }, { .name = "build C++ lexer generator", .out = "*compilation*", .footer_panel = true, .save_dirty_files = true,