Branch: Tag:

2017-03-17

2017-03-17 14:20:12 by Henrik Grubbström (Grubba) <grubba@grubba.org>

Documentation [MasterObject]: Documented some more stuff.

Also restructures the markup a bit.

430:   //! @[get_compat_master()]   protected inherit Pike_8_0_master;    - //! @appears error + //! @namespace predef:: +    //! Throws an error. A more readable version of the code   //! @expr{throw( ({ sprintf(f, @@args), backtrace() }) )@}.   void error(sprintf_format f, sprintf_args ... args) {
500:   #endif // PIKE_MODULE_RELOC       - //! @appears is_absolute_path +    //! Check if a path @[p] is fully qualified (ie not relative).   //!   //! @returns
529:   #define EXPLODE_PATH(X) ((X)/"/")   #endif    - //! @appears explode_path +    //! Split a path @[p] into its components.   //!   //! This function divides a path into its components. This might seem like
553:   #endif   }    - //! @appears dirname +    //! Returns all but the last segment of a path. Some example inputs and   //! outputs:   //!
584:   #endif   }    - //! @appears basename +    //! Returns the last segment of a path.   //!   //! @seealso
645:      #endif // PIKE_AUTORELOAD    - //! @appears compile_string +    //! Compile the Pike code in the string @[source] into a program.   //! If @[filename] is not specified, it will default to @expr{"-"@}.   //!
686:    return ret;   }    + //! @endnamespace +    //!   string master_read_file(string file)   {
873:   }   #endif    + //! @namespace predef:: +    //! @decl mapping(string:string) getenv (void|int force_update)   //!   //! Queries the environment variables.
997:   }       - //! @appears compile_file +    //! Compile the Pike code contained in the file @[filename] into a program.   //!   //! This function will compile the file @[filename] to a Pike program that can
1031:   }       - //! @appears normalize_path +    //! Replaces "\" with "/" if runing on MS Windows. It is   //! adviced to use @[System.normalize_path] instead.   string normalize_path( string path )
1043:   #endif   }    + //! @endnamespace +    //! Mapping containing the cache of currently compiled files.   //!   //! This mapping currently has the following structure:
1761:   #endif   });    - enum bool { false=0, true=1 }; -  +    //! Prefix for Pike-related C header files.   string include_prefix;   
1775:   //! Flags suitable for use when linking Pike C modules   string ldflags; // Not yet used    + //! @namespace predef:: + //! + //! This is the default namespace and contains lots of global symbols.    -  + //! Boolean datatype. + enum bool { false=0, true=1 }; +    //! @decl int write(string fmt, mixed ... args) - //! @appears write +    //! Writes a string on stdout. Works just like @[Stdio.File.write]   //! on @[Stdio.stdout].      //! @decl int werror(string fmt, mixed ... args) - //! @appears werror +    //! Writes a string on stderr. Works just like @[Stdio.File.write]   //! on @[Stdio.stderr].    -  + //! @decl array random(mapping m) + //! @decl float random(float max) + //! @decl int random(int max) + //! @decl mixed random(object o) + //! @decl mixed random(array|multiset x) + //! + //! Get a random value generated by the default @[RandomSystem]. + //! + //! @seealso + //! @[RandomSystem()->random()], @[random_string()] +  + //! @decl string random_string(int len) + //! + //! Get a string of random characters @expr{0..255@} with the length @[len] + //! from the default @[RandomSystem]. + //! + //! @seealso + //! @[RandomSystem()->random_string()], @[random()] +    /* Note that create is called before add_precompiled_program    */   protected void create()
1867:    system_module_path=pike_module_path;   }    + //! @endnamespace      //! This function is called whenever a inherit is called for.   //! It is supposed to return the program to inherit.
3174:      inherit CompatResolver;    + //! @namespace predef:: +  + //! @class __dirnode +  + //! @decl inherit MasterObject.dirnode +  + //! @endclass +  + //! @class __joinnode +  + //! @decl inherit MasterObject.joinnode +  + //! @endclass +  + //! @decl void add_include_path(string tmp) + //! Add a directory to search for include files. + //! + //! This is the same as the command line option @tt{-I@}. + //! + //! @note + //! Note that the added directory will only be searched when using + //! < > to quote the included file. + //! + //! @seealso + //! @[remove_include_path()] + //! +  + //! @decl void remove_include_path(string tmp) + //! Remove a directory to search for include files. + //! + //! This function performs the reverse operation of @[add_include_path()]. + //! + //! @seealso + //! @[add_include_path()] + //! +  + //! @decl void add_module_path(string path, string|void subpath) + //! Add a directory to search for modules. + //! + //! This is the same as the command line option @tt{-M@}. + //! + //! @seealso + //! @[remove_module_path()] + //! + //! @param path + //! a string containing a path to search for Pike modules. May be a + //! directory, or a path to a ZIP archive. If a ZIP archive path is + //! provided, modules will be loaded from a directory, "modules" within + //! the ZIP archive (see the subpath argument). + //! + //! @param subpath + //! if path is a ZIP archive, this argument will determine the path within + //! the archive to be searched. + //! +  + //! @decl void remove_module_path(string tmp) + //! Remove a directory to search for modules. + //! + //! This function performs the reverse operation of @[add_module_path()]. + //! + //! @seealso + //! @[add_module_path()] + //! +  + //! @decl void add_program_path(string tmp) + //! Add a directory to search for programs. + //! + //! This is the same as the command line option @tt{-P@}. + //! + //! @seealso + //! @[remove_program_path()] + //! +  + //! @decl void remove_program_path(string tmp) + //! Remove a directory to search for programs. + //! + //! This function performs the reverse operation of @[add_program_path()]. + //! + //! @seealso + //! @[add_program_path()] + //! +  + //! @endnamespace +    //! These are useful if you want to start other Pike processes   //! with the same options as this one was started with.   string _pike_file_name;
4409:    * readable message.    */    - //! @appears describe_backtrace + //! @namespace predef:: +    //! Return a readable message that describes where the backtrace   //! @[trace] was made (by @[backtrace]).   //!
4650:    return ret;   }    - //! @appears describe_error - //! +    //! Return the error message from an error object or array (typically   //! caught by a @[catch]). The type of the error is checked, hence   //! @[err] is declared as @expr{mixed@} and not @expr{object|array@}.
4701:    return sprintf ("<Invalid error container: %O>\n", err);   }    - //! @appears get_backtrace - //! +    //! Return the backtrace array from an error object or array   //! (typically caught by a @[catch]), or zero if there is none. Errors   //! are thrown on if there are problems retrieving the backtrace.
4740:    return bt;   }    + //! @endnamespace +    void thread_quanta_exceeded(object thread, int ns)   {    werror("Thread quanta exceeded for %O (%d ns):\n"