mono/docs/README

Documentation is now maintained on the mono wiki:

http://www.mono-project.com/Mono:Runtime:Documentation

Older documents or documents which were not yet migrated to the wiki are kept here.

* Scripts to maintain the Mono VM internal API

Layout
------

	sources/
		mono-api-*.html

		Contains the various source files, each source file
		contains HTML, and a line for each API call like this:

		<h4><a name="api:mono_something">mono_something</a></h4>

		The format is static, notice that the tools actually search
		for the above format and process that (both the tools here, 
	  	as well as the upcoming Monodoc tools and index creation
		tools).

		The files can contain any ammount of extra information.

		The documentation from the source code is then merged with 
		these files and the header/footer information to produce
		the deploy directory.

	deploy/

		Scripts produce a ready-to-use set of XHTML files that can
		be either fed into a monodoc XHTML provider or can be published
		directly on the web.

PROGRAMS
--------
* check-coverage

	Run this script every once in a while to make sure that a
	public symbol that has been added to Mono has a corresponding
	section on the mono-vm-api.html

	This works by looking for the <h4>APICALL</h4> pattern on the
	HTML file.
	
* produce-lists

	Produces the public-api and wapi files that contain the public
	libmono API.

* exdoc

	Extracts the embedded documentation from the sources.

* check

	This script is used to verify which routines are missing inline
	documentation, usage:

		check mono/metadata/*.c

* convert.cs

	Converts an HTML file into a valid XML document, uses the
	AgilityPack.dll.  The sources to this DLL live in GNOME CVS
	module beagle/Filters/AgilityPack.

	A binary is shipped for our convenience.

DATAFILES:
---------

	ignore

		Contains the list of public symbols that should be
		ignored, they come from tests for example, or are known
		to be exposed.

		This is consumed by produce-lists
	
	public-api 
	wapi
		These two are produced by the produce-lists script
		and it documents all the public methods.