browser.txt

来自「开放源码的编译器open watcom 1.6.0版的源代码」· 文本 代码 · 共 362 行

MODULES in the Optima++ browse merger
=====================================


Structure of this file
----------------------

For each module, the following information is given:
	-- name of the module
	-- files making up this module
	-- description of it's purpose
	-- classes defined within the module
	-- other information (e.g. functions or static information)
	-- comments
	
	
Module:	applic
--------------

Name:		applic
Files:		applic.cpp, applic.hpp
Purpose:	Handle Windows DLL functions.
Classes:	ApplicationClass -- inherited from WDLLApplication.

Comments:
	This code was generated by Optima++ when I first converted
	this project to use WClass and I'm more than happy to leave
	it alone, as I understand almost nothing about DLL's.
	

Module: avltree
---------------

Name:		avltree
Files:		avltree.cpp, avltree.hpp
Purpose:	Implement an AVL tree abstract data type.
Classes:	AvlTreeBase -- AVL tree ADT base class.
		AvlTree -- template interface to AvlTreeBase.
		
Comments:
	A nice balanced tree algorithm taken from Knuth via Anthony Scian.
	Good for fast insertion and searching, bad for saving memory, but
	I have tried to optimize the memory a little bit.
	
	
Module: brmerge	
---------------

Name:		brmerge
Files:		brmerge.cpp, brmerge.hpp, handle.hpp
Purpose:	The primary module.  Provides the interface to the DLL
		and implements all functions specified in the interface.
		Utilizes the other modules.
Classes:	SourceLocn -- structure specifying the name and/or location
			      of something in a target.
		Browser -- class implementing the top-level functionality
			  of the DLL.  Defined in handle.hpp.
Other info:	CurrBrowser -- global instance of the Browser class.
		For information on interface functions, see the "interface"
		document.

Comments:
	The big kahuna.  This is the largest module in the project,
	and it ties in all of the others.  This is also where browse
	files generated by the compiler are read in and manipulated.
	

Module: brmfile
---------------

Name:		brmfile
Files:		brmfile.cpp, brmfile.hpp
Purpose:	Handle the reading of browse files generated by the
		compiler.
Classes:	BrmFile -- read-only file class for browse files (*.BRM).
		BrmFilePch -- the same, but extracts browse information
			      from pre-compiled header files (*.PCH).
			      Inherits from BrmFile.

Comments:
	Mostly wrappers around stdio.h's FILE pointers.  BrmFilePch::Open
	contains code to skip to the browse section of a pre-compiled
	header, and then pretend that the browse info is in fact the entire
	file.
	
	Because this module reads in pre-compiled headers, it includes
	the file "h\pcheader.h" from the PLUSPLUS project.
	

Module: cache
-------------

Name:		cache
Files:		cache.cpp, cache.hpp
Purpose:	Handle saving and loading of post-merge browse information
		to disk.
Classes:	CacheOutFile -- save data to a file
		CacheInFile -- load the saved data
		CacheHeader -- internal to the module
		DirEntry -- internal to the module

Comments:
	Using the cache classes, data can be stored in any number of
	"components" within a disk file, each component identified by
	a string.  A "directory" of all components is included in the file
	when it's closed.  Some trivial compression is performed:  dwords
	are stored in 2 bytes instead of 4 bytes whenever they're small
	enough.
	
	
Module: debugprt
----------------

Name:		debugprt
Files:		debugprt.cpp, debugprt.hpp
Purpose:	Provide storage of messages as WStrings for debug purposes.
Classes:	DebugPrint -- wrapper around a WStringArray.
Other Info:	DebugPrinter -- global instance of the DebugPrint class.

Comments:
	I'm not using this as much as I should.


Module: decl
------------

Name:		decl
Files:		decl.cpp, decl.hpp
Purpose:	Handle browse information pertaining to symbols.
Classes:	DeclRec -- struct inherited from Hashable.
		DeclList -- container class for DeclRecs, inherited from
			    HashTable<DeclRec>.
			    
Comments:
	The DeclRec struct is mostly a copy of the BRI_Rec_Declaration
	records appearing in browse files.
	

Module: defn
------------

Name:		defn
Files:		defn.cpp, defn.hpp
Purpose:	Handle browse information pertaining to definitions.
Classes:	DefnRec -- struct inherited from Hashable.
		DefnList -- container class for DefnRecs, inherited from
			    HashTable<DeclRec>.
			    
Comments:
	The DefnRec struct is mostly a copy of the BRI_Rec_Definition
	records appearing in browse files.
	
	
Module: hashtbl
---------------

Name:		hashtbl
Files:		hashtbl.cpp, hashtbl.hpp
Purpose:	Implement hash table and linked list ADT's.
Classes:	Hashable -- struct used by HashTable
		HashTableBase -- hash table ADT base class.
		HashTable -- template interface to HashTableBase.
		LListBase -- linked list ADT base class.
		LList -- template interface to LListBase.
Other Info:	indexOf -- inline function for accessing Hashables.
		
Comments:
	HashTables can only be instatiated for classes which inherit
	from Hashable; the index and pointer fields used by the
	hash table algorithms appear there.  Any structure in the DLL
	which inherits from Hashable is stored in a HashTable.
	
	The LList class is used throughout the DLL as a stack data
	type, and in the few cases where data only needs to accessed
	sequentially.  It's much more memory-efficient than the AvlTree
	type, but of course is next to useless in random-access situations.
	
	
Module: macro
-------------

Name:		macro
Files:		macro.cpp, macro.hpp
Purpose:	Handle browse info for pre-processor information
		(both "guard" information and macros)
Classes:	DependValRec -- structure used to store certain
				dependancy information
		DependList -- container for dependancy information
			      (i.e. "#ifndef _FILE_INCLUDED" statements)
		StringIDs -- internal to the module
		FileGuardInfo -- internal to the module
		MacroList -- container for macro information
		
Comments:
	This module serves two purposes.
	
	First, it tries to eliminate some redundancy between different
	browse files.  If two browse files both include the same
	source or header file, and if the state of all preprocessor
	macros just before the file was included was the same both times,
	then the second inclusion is redundant and can be ignored.  The
	compiler emits special "guard" browse information to facilitate
	this, all of it related to pre-processor infomation such as
	"#ifndef _FILE_INCLUDED" statements.
	
	(Why is that always to hard to explain?)
	
	Second, it stores information for macros: what has been defined
	and where.
	
	
Module: main
------------

Name:		main
Files:		main.cpp, main.hpp
Purpose:	More Windows DLL-related incantations.
Classes:	NONE
Other info:	Application -- global instance of ApplicationClass

Comments:
	Another file generated by Optima++, bless its little heart.
	
	
Module: pool
------------

Name:		pool
Files:		pool.cpp, pool.hpp
Purpose:	Yet another memory manager
Classes:	Pool -- a carver class.
Other info:	PoolIds -- an enum used for debugging only.

Comments:
	This DLL can easily use several megabytes of RAM, and a lot of
	that in 10 or 12-byte structs, so this seemed like a good idea.
	Besides, I had the code lying around from a previous work term.
	Any structure which appears more than twice in the DLL should have
	a Pool class under the hood.
	
	Be warned that the code in this module is low-level and really,
	really, ugly.  (God help me, I quick-sorted a linked list.)  I've
	tried to simplify it as best as I can, but you might want to take
	a good LONG look before modifying it.
	
	
Module: ppops
-------------

Name:		ppops
Files:		ppops.cpp, ppops.hpp
Purpose:	Convert compiler-generated names into more sensible names
Classes:	NONE
Other info:	NameOfOp -- convert a compiler-generated name into an index
		OpNames -- table of operator names
		
Comments:
	Use this module to convert names of the form ".@aa" into names of
	the form "operator =".  This module doesn't handle the names ".@ct"
	(constructor), ".@cv" (conversion operator), and ".@dt" (destructor),
	other than to return a value indicating that the caller will have
	to look up a symbol name or type name.
	
	The information in this module was based on the information in
	the file "h\ppopsdef.h" in the PLUSPLUS project.
	
	
Module: reindex
---------------

Name:		reindex
Files:		reindex.cpp, reindex.hpp
Purpose:	Manage all of those 32-bit indices in browse files and
		prevent collisions between different browse files.
Classes:	UInt32Pair -- struct to hold two uint_32s, inherited from
			      Hashable
		ReOrdering -- tables of UInt32Pairs, inherited from
			      HashTable<Uint32Pair>
		PCHIndexRec -- internal to the module
		
Comments:
	The problem this module solves is, what if two different browse
	files contain records using the same 32-bit index and have to
	be merged?  The solution is to re-index every record that comes
	in and update all cross-references appropriately.  Pre-compiled
	headers complicate this somewhat.
	

Module: scopes
--------------

Name:		scopes
Files:		scopes.cpp, scopes.hpp
Purpose:	Handle browse information related to scopes.
Classes:	ScopeRec -- struct inherited from Hashable.
		ScopeTable -- container class for ScopeRec's, inherited
			      from HashTable<ScopeRec>.
			      
Comments:
	The ScopeRec struct is partly a copy of the BRI_Rec_Scope record
	appearing in browse files.  However, it also contains information
	about the scope tree (which is reconstructed during merging) and
	about the symbols and class types declared within the scope.
	
	
Module: strtable
----------------

Name:		strtable
Files:		strtable.cpp, strtable.hpp
Purpose:	Handle all strings.
Classes:	StringTable -- storage for all strings used by the DLL.

Comments:
	The code for StringTable is based on the code for HashTable.
	All strings are stored in a single continuous buffer.
	

Module: types
-------------

Name:		types
Files:		types.cpp, types.hpp
Purpose:	Handle browse information related to types.
Classes		TypeRec -- struct inherited from Hashable.
		TypeList -- container class for TypeRec's, inherited from
			    HashTable<TypeRec>.
			    
Comments:
	The TypeRec struct stores the same information as a BRI_Rec_Type
	record from a browse file, but stores it in the form of a typed
	union rather than a variable-length array of dwords.
	
	
Module: usage
-------------

Name:		usage
Files:		usage.cpp,usage.hpp
Purpose:	Handle browse information related to references.
Classes:	UsageRec -- structure holding information about a single
			    reference.
		UsageList -- container class for UsageRec's.
		
Comments:
	UsageRec's are stored on a per-source-file basis, sorted in
	order by line and column number.  The UsageRec struct is based
	on the BRI_Rec_Usage record appearing in browse files.
	

Module: wpch
------------

Name:		wpch
Files:		wpch.cpp, wpch.hpp
Purpose:	Ensure creation of the pre-compiled header for the DLL.
Classes:	NONE

Comments:
	Another gift from Optima++, although I've modified this one to
	put various standard library header files in the PCH.