Branch: Tag:

2014-10-18

2014-10-18 20:51:39 by Henrik Grubbström (Grubba) <grubba@grubba.org>

Doc: Added some Doxygen markup for C-level APIs.

1985:    return ret;   }    - /* This function is intended to simplify resolving of + /** +  * This function is intended to simplify resolving of    * program symbols during compile-time for C-modules.    *    * A typical use-case is for a C-module inheriting
2025:    *! @[this], @[this_object()]    */    - /* If the identifier is recognized as one of the magic identifiers, + /** +  * If the identifier is recognized as one of the magic identifiers,    * like "this", "this_program" or "`->" when preceded by ::, then a    * suitable node is returned, NULL otherwise.    * -  * inherit_num is -1 when no specific inherit has been specified; ie -  * either when the identifier has no prefix (colon_colon_ref == 0) or -  * when the identifier has the prefix :: without any preceding identifier -  * (colon_colon_ref == 1). +  * @param inherit_num +  * Inherit number in state->new_program that the identifier has been +  * qualified with. -1 when no specific inherit has been specified; ie +  * either when the identifier has no prefix (colon_colon_ref == 0) or +  * when the identifier has the prefix :: without any preceding identifier +  * (colon_colon_ref == 1).    *    * New in Pike 7.9.5 and later:    *
2331:    * end_first_pass(1) ==> PROGRAM_FINISHED    */    - /* Re-allocate all the memory in the program in one chunk. because: -  * 1) The individual blocks are much bigger than they need to be -  * 2) cuts down on malloc overhead (maybe) -  * 3) localizes memory access (decreases paging) + /** +  * Re-allocate all the memory in the program in one chunk. because: +  * @b 1) The individual blocks are much bigger than they need to be +  * @b 2) cuts down on malloc overhead (maybe) +  * @b 3) localizes memory access (decreases paging)    */   void optimize_program(struct program *p)   {
2869:    return p;   }    - /* + /**    * Start building a new program    */   void low_start_new_program(struct program *p,
3951:    IDENTIFIER_C_FUNCTION, &dispatch_fun, 0);   }    - /* Note: This function is misnamed, since it's run after both passes. /mast */ - /* finish-states: + /** +  * End the current compilation pass.    * -  +  * @param finish +  * finish-state: +  *    * 0: First pass.    * 1: Last pass.    * 2: Called from decode_value(). -  +  * +  * Note: This function is misnamed, since it's run after all passes.    */   struct program *end_first_pass(int finish)   {
4217:    return prog;   }    - /* + /**    * Finish this program, returning the newly built program    */   PMOD_EXPORT struct program *debug_end_program(void)
4226:   }       - /* + /**    * Allocate space needed for this program in the object structure.    * An offset to the data is returned.    */
4359:    }   }    - /* + /**    * Set a callback to be called when this program is cloned.    *    * This function is obsolete; see pike_set_prog_event_callback for
4371:    ((oldhandlertype *)Pike_compiler->new_program->program)[PROG_EVENT_INIT]=init;   }    - /* + /**    * Set a callback to be called when clones of this program are    * destructed.    *
4395:    Pike_compiler->new_program->flags |= PROGRAM_LIVE_OBJ;   }    - /* + /**    * This callback is used by the gc to traverse all references to    * things in memory. It should call some gc_recurse_* function exactly    * once for each reference that the pike internals doesn't know about.
4430:    ((oldhandlertype *)Pike_compiler->new_program->program)[PROG_EVENT_GC_RECURSE]=m;   }    - /* + /**    * This callback is used by the gc to count all references to things    * in memory. It should call gc_check, gc_check_(weak_)svalues or    * gc_check_(weak_)short_svalue exactly once for each reference that
4452:    ((oldhandlertype *)Pike_compiler->new_program->program)[PROG_EVENT_GC_CHECK]=m;   }    - /* + /**    * Set a callback to be called when any of the special program events    * occur. The event type is sent as an integer argument. The events    * include, but might not be limited to, the following:
4501:    Pike_compiler->new_program->optimize = opt;   }    + /** +  * Reference an inherited identifier. +  * +  * @param q +  * Program state for the program being compiled that will have +  * the reference added. May be NULL to indicate Pike_compiler. +  * +  * @param i +  * Inherit number in q->new_program. +  * +  * @param f +  * Reference number in q->new_program->inherit[i].prog. +  * +  * @return +  * Returns an equivalent reference that is INLINE|HIDDEN. +  */   PMOD_EXPORT int really_low_reference_inherited_identifier(struct program_state *q,    int i,    int f)
4605:    return res;   }    - /* Reference the symbol inherit::name in the lexical context + /** +  * Reference the symbol inherit::name in the lexical context    * specified by state.    * -  * Returns the reference in state->new_program if found. +  * @return Returns the reference in state->new_program if found.    */   PMOD_EXPORT int reference_inherited_identifier(struct program_state *state,    struct pike_string *inherit,
4978:    Pike_compiler->flags |= COMPILATION_CHECK_FINAL;    }    +  if (flags & ID_PUBLIC) +  fun.id_flags &= ~(ID_PRIVATE|ID_PUBLIC); +     if(fun.id_flags & ID_PRIVATE) fun.id_flags|=ID_HIDDEN;    -  if (fun.id_flags & ID_PUBLIC) -  fun.id_flags |= flags & ~ID_PRIVATE; -  else -  fun.id_flags |= flags; +  fun.id_flags |= flags & ~ID_PUBLIC;       fun.id_flags |= ID_INHERITED;    add_to_identifier_references(fun);    }   }    - /* -  * make this program inherit another program + /** +  * Make the program being compiled inherit another program. +  * +  * @param p +  * Program to inherit. +  * +  * @param parent +  * Object containing p (if applicable). +  * +  * @param parent_identifier +  * Identifier reference in parent->prog that is p. +  * +  * @param parent_offset +  * Lexical scope to parent from the program being compiled +  * offsetted by 42, or OBJECT_PARENT or INHERIT_PARENT. +  * +  * @param flags +  * Modifier flags for the inherit. +  * +  * @param name +  * Optional rename of the inherit.    */   PMOD_EXPORT void low_inherit(struct program *p,    struct object *parent,
5159:    pop_stack();   }    - /* -  * Return the index of the identifier found, otherwise -1. + /** +  * Find an identifier relative to the program being compiled. +  * +  * @return Return the index of the identifier found, otherwise -1.    */   int isidentifier(struct pike_string *s)   {
5183:    */       - /* Define an alias for a (possibly extern) identifier. + /** +  * Define an alias for a (possibly extern) identifier.    *    * Note that both type and name may be NULL. If they are NULL    * they will be defaulted to the values from the aliased identifier.
6007:    return ret;   }    - /* -  * define a new function + /** +  * Define a new function. +  *    * if func isn't given, it is supposed to be a prototype.    */   INT32 define_function(struct pike_string *name,
6532:      #endif /* 0 */    - /* Identifier lookup + /** +  * Identifier lookup    *    * The search algorithm has changed several times during Pike 7.3.    *
6908:    return -1;   }    - /* -  * lookup the number of a function in a program given the name in + /** +  * Lookup the number of a function in a program given the name in    * a shared_string    */   int low_find_shared_string_identifier(struct pike_string *name,
7699:    }   }    - /* Same as low_get_program_line but returns a plain char *. It's + /** +  * Same as low_get_program_line but returns a plain char *. It's    * malloced if the malloced flag is set, otherwise it's a pointer to a    * static buffer which might be clobbered by later calls.    *
7724:    return NULL;   }    - /* Returns the file where the program is defined. The line of the + /** +  * Returns the file where the program is defined. The line of the    * class start is written to linep, or 0 if the program is the top -  * level of the file. */ +  * level of the file. +  */   PMOD_EXPORT struct pike_string *get_program_line(struct program *prog,    INT_TYPE *linep)   {
7802:    return NULL;   }    - /* This is to low_get_line as low_get_program_line_plain is to -  * low_get_program_line. */ + /** +  * This is to low_get_line as low_get_program_line_plain is to +  * low_get_program_line. +  */   PMOD_EXPORT char *low_get_line_plain (PIKE_OPCODE_T *pc, struct program *prog,    INT_TYPE *linep, int malloced)   {
7861:      #endif    - /* -  * return the file in which we were executing. pc should be the + /** +  * Return the file in which we were executing. pc should be the    * program counter (i.e. the address in prog->program), prog the    * current program, and line will be initialized to the line in that    * file.
7923:    return NULL;   }    - /* Return the file and line where the identifier with reference number + /** +  * Return the file and line where the identifier with reference number    * fun was defined.    *    * Note: Unlike the other get*line() functions, this one does not
7941:    return p->strings[id->filename_strno];   }    - /* Main entry point for compiler messages originating from -  * C-code. + /** +  * Main entry point for compiler messages originating from C-code.    *    * Sends the message along to PikeCompiler()->report().    *
8076:    my_yyerror("%s", str);   }    - /* Main entry point for errors from the type-checking subsystems. + /** +  * Main entry point for errors from the type-checking subsystems.    *    * The message (if any) will be formatted for the same source    * position as the got_t.
10153:    push_string(finish_string_builder(&buf));   }    - /* Fake being called via PikeCompiler()->compile() + /** +  * Fake being called via PikeCompiler()->compile()    *    * This function is used to set up the environment for    * compiling C efuns and modules.
10222:    }   }    - /* Reverse the effect of enter_compiler(). + /** +  * Reverse the effect of enter_compiler().    */   PMOD_EXPORT void exit_compiler(void)   {
10271:   /*! @endclass    */    - /* Strap the compiler by creating the compilation program by hand. */ + /** +  * Strap the compiler by creating the compilation program by hand. +  */   static void compile_compiler(void)   {    struct program *p = low_allocate_program();
11693:          - /* returns 1 if a implements b */ + /** +  * @return Returns 1 if a implements b. +  */   static int low_implements(struct program *a, struct program *b)   {    DECLARE_CYCLIC();
11756:    return ((aid<<4) ^ bid ^ (aid>>4)) & (IMPLEMENTS_CACHE_SIZE-1);   }    - /* returns 1 if a implements b, but faster */ + /** +  * @return Returns 1 if a implements b, but faster. +  */   PMOD_EXPORT int implements(struct program *a, struct program *b)   {    unsigned long hval;
11779:    return implements_cache[hval].ret;   }    - /* Returns 1 if a is compatible with b */ + /** +  * @return Returns 1 if a is compatible with b. +  */   static int low_is_compatible(struct program *a, struct program *b)   {    DECLARE_CYCLIC();
11834:   }      static struct implements_cache_s is_compatible_cache[IMPLEMENTS_CACHE_SIZE]; - /* Returns 1 if a is compatible with b + /** +  * Returns 1 if a is compatible with b. +  *    * ie it's possible to write a hypothetical c that implements both.    */   PMOD_EXPORT int is_compatible(struct program *a, struct program *b)
11886:    return is_compatible_cache[hval].ret;   }    - /* Explains why a is not compatible with b */ + /** +  * Explains why a is not compatible with b. +  */   void yyexplain_not_compatible(int severity_level,    struct program *a, struct program *b)   {
11956:    return;   }    - /* Explains why a does not implement b */ + /** +  * Explains why a does not implement b. +  */   void yyexplain_not_implements(int severity_level,    struct program *a, struct program *b)   {
12029:   }      /* FIXME: Code duplication of yyexplain_not_compatible() above! */ - /* Explains why a is not compatible with b */ + /** +  * Explains why a is not compatible with b. +  */   void string_builder_explain_not_compatible(struct string_builder *s,    struct program *a,    struct program *b)
12093:   }      /* FIXME: code duplication of yyexplain_not_implements() above! */ - /* Explains why a does not implement b */ + /** +  * Explains why a does not implement b. +  */   void string_builder_explain_not_implements(struct string_builder *s,    struct program *a,    struct program *b)