Version 2 (modified by mikehh, 5 years ago)

correct some pasting errors and remove fixed src/nci_test.c (at r43473)

Missing C Function Documentation

The following is extracted from the test t/codingstd/c_function_docs.t.

The following gives the C source file in single quotes, followed by the output for the test - prefixed by #

It gives the number of functions missing documentation in the source file, then the function(s) missing documentation, and what the test expects to be there (Want:).

Bear in mind we are dealing with POD and that it expects a maximum line length of 78.

as of r43473 the following C functions are missing documentation:

'examples/c/pbc_info.c'

# 1 function(s) lacking documentation:
# examples/c/pbc_info.c (missing)
# static INTVAL
# iter(PARROT_INTERP, PackFile_Segment *seg, void *user_data)
# Want:
# =item C<static INTVAL iter(PARROT_INTERP, PackFile_Segment *seg, void
# *user_data)>

'src/atomic/gcc_x86.c'

# 2 function(s) lacking documentation:
# src/atomic/gcc_x86.c (missing)
# PARROT_EXPORT
# PARROT_CANNOT_RETURN_NULL
# void *
# parrot_i386_cmpxchg(ARGMOD(void *volatile *ptr), ARGIN_NULLOK(void *expect),
#                                         ARGIN_NULLOK(void *update))
# Want:
# =item C<void * parrot_i386_cmpxchg(void *volatile *ptr, void *expect, void
# *update)>
#
# src/atomic/gcc_x86.c (missing)
# PARROT_EXPORT
# long
# parrot_i386_xadd(ARGIN(volatile long *l), long amount)
# Want:
# =item C<long parrot_i386_xadd(volatile long *l, long amount)>

'compilers/pirc/src/pircompiler.c'

# 6 function(s) lacking documentation:
# compilers/pirc/src/pircompiler.c (missing)
# PARROT_MALLOC
# PARROT_CANNOT_RETURN_NULL
# PARROT_WARN_UNUSED_RESULT
# static allocated_mem_ptrs *
# new_mem_ptrs_block(void)
# Want:
# =item C<static allocated_mem_ptrs * new_mem_ptrs_block(void)>
#
# compilers/pirc/src/pircompiler.c (missing)
# void
# init_hashtable(NOTNULL(lexer_state * const lexer), NOTNULL(hashtable * const table),
#                unsigned size)
# Want:
# =item C<void init_hashtable(lexer_state * const lexer, hashtable * const table,
# unsigned size)>
#
# compilers/pirc/src/pircompiler.c (missing)
# PARROT_CANNOT_RETURN_NULL
# PARROT_WARN_UNUSED_RESULT
# bucket *
# new_bucket(NOTNULL(lexer_state * const lexer))
# Want:
# =item C<bucket * new_bucket(lexer_state * const lexer)>
#
# compilers/pirc/src/pircompiler.c (missing)
# PARROT_WARN_UNUSED_RESULT
# PARROT_CANNOT_RETURN_NULL
# char const *
# dupstr(NOTNULL(lexer_state * const lexer), NOTNULL(char * const source))
# Want:
# =item C<char const * dupstr(lexer_state * const lexer, char * const source)>
#
# compilers/pirc/src/pircompiler.c (missing)
# void
# release_resources(NOTNULL(lexer_state *lexer))
# Want:
# =item C<void release_resources(lexer_state *lexer)>
#
# compilers/pirc/src/pircompiler.c (missing)
# void
# pirwarning(lexer_state * const lexer, int lineno, char const * const message, ...)
# Want:
# =item C<void pirwarning(lexer_state * const lexer, int lineno, char const *
# const message, ...)>

'compilers/pirc/src/piremit.c'

# 20 function(s) lacking documentation:
# compilers/pirc/src/piremit.c (missing)
# void
# print_key(lexer_state * const lexer, key * const k)
# Want:
# =item C<void print_key(lexer_state * const lexer, key * const k)>
#
# compilers/pirc/src/piremit.c (missing)
# void
# print_target(lexer_state * const lexer, target * const t)
# Want:
# =item C<void print_target(lexer_state * const lexer, target * const t)>
#
# compilers/pirc/src/piremit.c (missing)
# void
# print_constant(lexer_state * const lexer, constant * const c)
# Want:
# =item C<void print_constant(lexer_state * const lexer, constant * const c)>
#
# compilers/pirc/src/piremit.c (missing)
# void
# print_expr(lexer_state * const lexer, expression * const expr)
# Want:
# =item C<void print_expr(lexer_state * const lexer, expression * const expr)>
#
# compilers/pirc/src/piremit.c (missing)
# void
# print_expressions(lexer_state * const lexer, expression * const expr)
# Want:
# =item C<void print_expressions(lexer_state * const lexer, expression * const
# expr)>
#
# compilers/pirc/src/piremit.c (missing)
# void
# print_statement(lexer_state * const lexer, subroutine * const sub)
# Want:
# =item C<void print_statement(lexer_state * const lexer, subroutine * const sub)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# print_sub_flags(lexer_state * const lexer, subroutine * const subiter)
# Want:
# =item C<static void print_sub_flags(lexer_state * const lexer, subroutine *
# const subiter)>
#
# compilers/pirc/src/piremit.c (missing)
# void
# print_subs(struct lexer_state * const lexer)
# Want:
# =item C<void print_subs(struct lexer_state * const lexer)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pir_instruction(lexer_state * const lexer, instruction * const instr)
# Want:
# =item C<static void emit_pir_instruction(lexer_state * const lexer, instruction
# * const instr)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pir_statement(lexer_state * const lexer, subroutine * const sub)
# Want:
# =item C<static void emit_pir_statement(lexer_state * const lexer, subroutine *
# const sub)>
#
# compilers/pirc/src/piremit.c (missing)
# void
# emit_pir_subs(lexer_state * const lexer, char const * const outfile)
# Want:
# =item C<void emit_pir_subs(lexer_state * const lexer, char const * const
# outfile)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pbc_const_arg(lexer_state * const lexer, constant * const c)
# Want:
# =item C<static void emit_pbc_const_arg(lexer_state * const lexer, constant *
# const c)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pbc_label_arg(lexer_state * const lexer, label * const l)
# Want:
# =item C<static void emit_pbc_label_arg(lexer_state * const lexer, label * const
# l)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pbc_target_arg(lexer_state * const lexer, target * const t)
# Want:
# =item C<static void emit_pbc_target_arg(lexer_state * const lexer, target *
# const t)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pbc_expr(lexer_state * const lexer, expression * const operand)
# Want:
# =item C<static void emit_pbc_expr(lexer_state * const lexer, expression * const
# operand)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# optimize_instr(lexer_state * const lexer, instruction * const instr)
# Want:
# =item C<static void optimize_instr(lexer_state * const lexer, instruction *
# const instr)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pbc_instr(lexer_state * const lexer, instruction * const instr)
# Want:
# =item C<static void emit_pbc_instr(lexer_state * const lexer, instruction *
# const instr)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pbc_sub(lexer_state * const lexer, subroutine * const sub)
# Want:
# =item C<static void emit_pbc_sub(lexer_state * const lexer, subroutine * const
# sub)>
#
# compilers/pirc/src/piremit.c (missing)
# static void
# emit_pbc_annotations(lexer_state * const lexer)
# Want:
# =item C<static void emit_pbc_annotations(lexer_state * const lexer)>
#
# compilers/pirc/src/piremit.c (missing)
# void
# emit_pbc(lexer_state * const lexer, const char *outfile)
# Want:
# =item C<void emit_pbc(lexer_state * const lexer, const char *outfile)>

'compilers/pirc/src/pirmacro.c'

# 4 function(s) lacking documentation:
# compilers/pirc/src/pirmacro.c (missing)
# PARROT_MALLOC
# PARROT_IGNORABLE_RESULT
# macro_def *
# new_macro(macro_table * const table, char const * const name, int lineno, int takes_args,
#           unsigned initsize)
# Want:
# =item C<macro_def * new_macro(macro_table * const table, char const * const
# name, int lineno, int takes_args, unsigned initsize)>
#
# compilers/pirc/src/pirmacro.c (missing)
# void
# new_macro_const(macro_table * const table, char const * const name, char const * const value,
#                       int lineno)
# Want:
# =item C<void new_macro_const(macro_table * const table, char const * const name,
# char const * const value, int lineno)>
#
# compilers/pirc/src/pirmacro.c (missing)
# void
# store_macro_string(macro_def * const macro, char const * const str, ...)
# Want:
# =item C<void store_macro_string(macro_def * const macro, char const * const str,
# ...)>
#
# compilers/pirc/src/pirmacro.c (missing)
# void
# delete_macro_table(macro_table * table)
# Want:
# =item C<void delete_macro_table(macro_table * table)>

'compilers/pirc/src/pirpcc.c'

# 17 function(s) lacking documentation:
# compilers/pirc/src/pirpcc.c (missing)
# static target *
# generate_unique_pir_reg(lexer_state * const lexer, pir_type type)
# Want:
# =item C<static target * generate_unique_pir_reg(lexer_state * const lexer,
# pir_type type)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static int
# generate_signature_pmc(lexer_state * const lexer, unsigned size)
# Want:
# =item C<static int generate_signature_pmc(lexer_state * const lexer, unsigned
# size)>
#
# compilers/pirc/src/pirpcc.c (missing)
# void
# emit_sub_epilogue(lexer_state * const lexer)
# Want:
# =item C<void emit_sub_epilogue(lexer_state * const lexer)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# add_alias_operand(lexer_state * const lexer, PMC *array, int index, char const * const alias)
# Want:
# =item C<static void add_alias_operand(lexer_state * const lexer, PMC *array, int
# index, char const * const alias)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# targets_to_operands(lexer_state * const lexer, target * const targets, unsigned num_targets)
# Want:
# =item C<static void targets_to_operands(lexer_state * const lexer, target *
# const targets, unsigned num_targets)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# arguments_to_operands(lexer_state * const lexer, argument * const args, unsigned num_arguments)
# Want:
# =item C<static void arguments_to_operands(lexer_state * const lexer, argument *
# const args, unsigned num_arguments)>
#
# compilers/pirc/src/pirpcc.c (missing)
# void
# generate_parameters_instr(lexer_state * const lexer, unsigned num_parameters)
# Want:
# =item C<void generate_parameters_instr(lexer_state * const lexer, unsigned
# num_parameters)>
#
# compilers/pirc/src/pirpcc.c (missing)
# void
# generate_getresults_instr(lexer_state * const lexer, target * const targetlist)
# Want:
# =item C<void generate_getresults_instr(lexer_state * const lexer, target * const
# targetlist)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# save_global_reference(lexer_state * const lexer, instruction * const instr,
#                       char const * const label)
# Want:
# =item C<static void save_global_reference(lexer_state * const lexer, instruction
# * const instr, char const * const label)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# convert_pcc_call(lexer_state * const lexer, invocation * const inv)
# Want:
# =item C<static void convert_pcc_call(lexer_state * const lexer, invocation *
# const inv)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# convert_pcc_tailcall(lexer_state * const lexer, invocation * const inv)
# Want:
# =item C<static void convert_pcc_tailcall(lexer_state * const lexer, invocation *
# const inv)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# convert_pcc_return(lexer_state * const lexer, inok 41 - compilers/pirc/src/pirop.c
vocation * const inv)
# Want:
# =item C<static void convert_pcc_return(lexer_state * const lexer, invocation *
# const inv)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# convert_nci_call(lexer_state * const lexer, invocation * const inv)
# Want:
# =item C<static void convert_nci_call(lexer_state * const lexer, invocation *
# const inv)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# convert_pcc_yield(lexer_state * const lexer, invocation * const inv)
# Want:
# =item C<static void convert_pcc_yield(lexer_state * const lexer, invocation *
# const inv)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# convert_pcc_methodcall(lexer_state * const lexer, invocation * const inv)
# Want:
# =item C<static void convert_pcc_methodcall(lexer_state * const lexer, invocation
# * const inv)>
#
# compilers/pirc/src/pirpcc.c (missing)
# static void
# convert_pcc_methodtailcall(lexer_state * const lexer, invocation * const inv)
# Want:
# =item C<static void convert_pcc_methodtailcall(lexer_state * const lexer,
# invocation * const inv)>
#
# compilers/pirc/src/pirpcc.c (missing)
# void
# convert_inv_to_instr(lexer_state * const lexer, invocation * const inv)
# Want:
# =item C<void convert_inv_to_instr(lexer_state * const lexer, invocation * const
# inv)>

'compilers/pirc/src/pirregalloc.c'

# 4 function(s) lacking documentation:
# compilers/pirc/src/pirregalloc.c (missing)
# void
# destroy_linear_scan_register_allocator(lsr_allocator *lsr)
# Want:
# =item C<void destroy_linear_scan_register_allocator(lsr_allocator *lsr)>
#
# compilers/pirc/src/pirregalloc.c (missing)
# PARROT_MALLOC
# PARROT_WARN_UNUSED_RESULT
# live_interval *
# new_live_interval(lsr_allocator * const lsr, unsigned firstuse_location, pir_type type)
# Want:
# =item C<live_interval * new_live_interval(lsr_allocator * const lsr, unsigned
# firstuse_location, pir_type type)>
#
# compilers/pirc/src/pirregalloc.c (missing)
# static void
# add_free_reg(lsr_allocator * const lsr, unsigned regno, pir_type type)
# Want:
# =item C<static void add_free_reg(lsr_allocator * const lsr, unsigned regno,
# pir_type type)>
#
# compilers/pirc/src/pirregalloc.c (missing)
# static void
# expire_old_intervals(lsr_allocator * const lsr, live_interval * const i, pir_type type)
# Want:
# =item C<static void expire_old_intervals(lsr_allocator * const lsr,
# live_interval * const i, pir_type type)>

'compilers/pirc/src/pirsymbol.c'

# 7 function(s) lacking documentation:
# compilers/pirc/src/pirsymbol.c (missing)
# static int
# next_register(NOTNULL(lexer_state * const lexer), pir_type type)
# Want:
# =item C<static int next_register(lexer_state * const lexer, pir_type type)>
#
# compilers/pirc/src/pirsymbol.c (missing)
# PARROT_WARN_UNUSED_RESULT
# PARROT_CANNOT_RETURN_NULL
# bucket *
# get_bucket(NOTNULL(hashtable * const table), unsigned long hash)
# Want:
# =item C<bucket * get_bucket(hashtable * const table, unsigned long hash)>
#
# compilers/pirc/src/pirsymbol.c (missing)
# void
# declare_local(NOTNULL(lexer_state * const lexer), pir_type type,
#               NOTNULL(symbol * const list))
# Want:
# =item C<void declare_local(lexer_state * const lexer, pir_type type, symbol *
# const list)>
#
# compilers/pirc/src/pirsymbol.c (missing)
# void
# check_unused_symbols(NOTNULL(lexer_state * const lexer))
# Want:
# =item C<void check_unused_symbols(lexer_state * const lexer)>
#
# compilers/pirc/src/pirsymbol.c (missing)
# static int
# use_register(NOTNULL(lexer_state * const lexer), pir_type type, int regno, int pasmregno)
# Want:
# =item C<static int use_register(lexer_state * const lexer, pir_type type, int
# regno, int pasmregno)>
#
# compilers/pirc/src/pirsymbol.c (missing)
# PARROT_WARN_UNUSED_RESULT
# PARROT_CANNOT_RETURN_NULL
# static local_label *
# new_local_label(NOTNULL(lexer_state * const lexer), NOTNULL(char const * const name),
#                 unsigned offset)
# Want:
# =item C<static local_label * new_local_label(lexer_state * const lexer, char
# const * const name, unsigned offset)>
#
# compilers/pirc/src/pirsymbol.c (missing)
# void
# store_local_label(NOTNULL(lexer_state * const lexer), NOTNULL(char const * const labelname),
#                   unsigned offset)
# Want:
# =item C<void store_local_label(lexer_state * const lexer, char const * const
# labelname, unsigned offset)>

'config/gen/platform/generic/env.c'

# 3 function(s) lacking documentation:
# config/gen/platform/generic/env.c (missing)
# void
# Parrot_setenv(PARROT_INTERP, STRING *str_name, STRING *str_value)
# Want:
# =item C<void Parrot_setenv(PARROT_INTERP, STRING *str_name, STRING *str_value)>
#
# config/gen/platform/generic/env.c (missing)
# void
# Parrot_unsetenv(PARROT_INTERP, STRING *str_name)
# Want:
# =item C<void Parrot_unsetenv(PARROT_INTERP, STRING *str_name)>
#
# config/gen/platform/generic/env.c (missing)
# char *
# Parrot_getenv(PARROT_INTERP, STRING *str_name)
# Want:
# =item C<char * Parrot_getenv(PARROT_INTERP, STRING *str_name)>

'config/gen/platform/generic/memalign.c'

# 3 function(s) lacking documentation:
# config/gen/platform/generic/memalign.c (boilerplate only)
# In:
# =item C<void * Parrot_memalign(size_t align, size_t size)>
#
# config/gen/platform/generic/memalign.c (boilerplate only)
# In:
# =item C<void * Parrot_memalign(size_t align, size_t size)>
#
# config/gen/platform/generic/memalign.c (boilerplate only)
# In:
# =item C<void Parrot_free_memalign(void *p)>

'config/gen/platform/generic/memexec.c'

# 2 function(s) lacking documentation:
# config/gen/platform/generic/memexec.c (missing)
# void
# mem_free_executable(void *p, size_t size)
# Want:
# =item C<void mem_free_executable(void *p, size_t size)>
#
# config/gen/platform/generic/memexec.c (missing)
# void *
# mem_realloc_executable(void* oldp, size_t oldsize, size_t newsize)
# Want:
# =item C<void * mem_realloc_executable(void* oldp, size_t oldsize, size_t
# newsize)>

'config/gen/platform/openbsd/memexec.c'

# 1 function(s) lacking documentation:
# config/gen/platform/openbsd/memexec.c (missing)
# void *
# mem_realloc_executable(void* oldp, size_t oldsize, size_t newsize)
# Want:
# =item C<void * mem_realloc_executable(void* oldp, size_t oldsize, size_t
# newsize)>

'src/pbc_dump.c'

# 4 function(s) lacking documentation:
# src/pbc_dump.c (missing)
# static void
# const_dump(PARROT_INTERP, const PackFile_Segment *segp)
# Want:
# =item C<static void const_dump(PARROT_INTERP, const PackFile_Segment *segp)>
#
# src/pbc_dump.c (missing)
# static void
# fixup_dump(PARROT_INTERP, const PackFile_Segment *segp)
# Want:
# =item C<static void fixup_dump(PARROT_INTERP, const PackFile_Segment *segp)>
#
# src/pbc_dump.c (missing)
# static void
# disas_dump(PARROT_INTERP, const PackFile_Segment *self)
# Want:
# =item C<static void disas_dump(PARROT_INTERP, const PackFile_Segment *self)>
#
# src/pbc_dump.c (missing)
# static void
# PackFile_header_dump(PARROT_INTERP, PackFile *pf)
# Want:
# =item C<static void PackFile_header_dump(PARROT_INTERP, PackFile *pf)>

'include/parrot/atomic/gcc_pcc.h'

# 2 function(s) lacking documentation:
# include/parrot/atomic/gcc_pcc.h (missing)
# inline static void *parrot_ppc_cmpset(void * volatile *ptr,
#                                       void *expect, void *update)
# Want:
# =item C<inline static void *parrot_ppc_cmpset(void * volatile *ptr, void
# *expect, void *update)>
#
# include/parrot/atomic/gcc_pcc.h (missing)
# inline static long parrot_ppc_add(volatile long *val, long what)
# Want:
# =item C<inline static long parrot_ppc_add(volatile long *val, long what)>