mr4th-public
/
4coder
1
Fork 0
Code Issues Releases Activity

Finished documentation, beginning to organize to acquire doc content at run time

master
Allen Webster 2019-12-10 10:46:12 -08:00
parent 8e9fbbbba6
commit 74adc4782f
17 changed files with 1497 additions and 839 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
4ed_api_implementation.cpp
View File

@ -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

13
4ed_app_target.cpp
View File

@ -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"

24
docs/4ed_doc_content_types.h → custom/4coder_doc_content_types.h
View File

@ -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

10
custom/4coder_docs.cpp Normal file
View File

@ -0,0 +1,10 @@
/*
4coder_docs.cpp - Documentation explorers
*/
// TOP
// BOTTOM

4
custom/4coder_lists.cpp
View File

@ -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

1
custom/4coder_profile.cpp
View File

@ -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*

3
custom/4coder_profile_inspect.cpp
View File

@ -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;

8
custom/generated/command_metadata.h
View File

@ -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 },

12
custom/generated/custom_api.h
View File

@ -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);

2
custom/generated/custom_api_master_list.h
View File

@ -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);

790
docs/4ed_doc_custom_api.cpp
View File

@ -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 <stdio.h>
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

95
docs/4ed_doc_custom_api_buffer.cpp
View File

@ -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");
}
}

311
docs/4ed_doc_custom_api_draw.cpp Normal file
View File

@ -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

944
docs/4ed_doc_custom_api_global.cpp
View File

@ -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

72
docs/4ed_doc_custom_api_main.cpp Normal file
View File

@ -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 <stdio.h>
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

31
docs/4ed_doc_helper.h Normal file
View File

@ -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

2
project.4coder
View File

@ -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,