* Makefile.am: Build docs after runtime, so that it can depend

	  upon mdoc.exe for it's operation.
	* docs/. (svn:ignore), deploy (svn:ignore): Ignore generated files.
	* docs/AgilityPack.dll, docs/api-style.css, docs/ChangeLog, docs/check,
	  docs/check-coverage, docs/convert.cs, docs/current-api, docs/deploy, 
	  docs/documented, docs/exdoc, docs/ignore, 
	  docs/mono-api-metadata.html, docs/monoapi.source, docs/produce-lists,
	  docs/public, docs/public-api, docs/README, docs/sources, 
	  docs/toc.xml, docs/TODO, docs/wapi: Copy from ../mono/docscripts.
	* docs/exdoc: Use the in-tree mono program to run convert.exe.
	* docs/Makefile.am: Mention files to clean/distribute; extract
	  documentation (with exdoc) and then assemble documentation (with
	  monoapi.make's assemble target) for use by monodoc.
	* docs/monoapi.make: Added; Makefile to use mcs' buid/rules.make to compile
	  convert.cs and assemble documentation.  (This is a separate file so
	  that we can include mcs' build/rules.make, which needs topdir set to
	  behave properly BUT must be $(mcs_topdir) from Makefile.am's
	  perspective.)
	* docs/monoapi.source: Add a /monodoc/node element for use with monodoc 2.2.

svn path=/trunk/mono/; revision=117529

ChangeLog

@@ -1,3 +1,8 @@
+2008-10-30  Jonathan Pryor  <[email protected]>
+
+	* Makefile.am: Build `docs` after `runtime`, so that it can depend
+	  upon mdoc.exe for it's operation.
+
 2008-10-30  Jonathan Pryor  <[email protected]>
 
 	* man/mdoc-assemble.1: Document //node use within .source files.

Makefile.am

@@ -1,11 +1,11 @@
 AUTOMAKE_OPTIONS = foreign
 ACLOCAL_AMFLAGS = -I .
 
-SUBDIRS = po $(libgc_dir) $(eglib_dir) mono $(ikvm_native_dir) support docs data runtime scripts man samples web msvc
+SUBDIRS = po $(libgc_dir) $(eglib_dir) mono $(ikvm_native_dir) support data runtime scripts man samples web msvc docs
 
 # Keep in sync with SUBDIRS
 ## 'tools' is not normally built
-DIST_SUBDIRS = po libgc $(eglib_dir) mono ikvm-native support docs data runtime scripts man samples web tools msvc
+DIST_SUBDIRS = po libgc $(eglib_dir) mono ikvm-native support data runtime scripts man samples web tools msvc docs
 
 EXTRA_DIST= nls.m4 po.m4 progtest.m4 mono-uninstalled.pc.in dtrace-prelink.sh build-mingw32.sh LICENSE mkinstalldirs
 

docs/ChangeLog

@@ -0,0 +1,28 @@
+2008-10-30  Jonathan Pryor  <[email protected]>
+
+	* . (svn:ignore), deploy (svn:ignore): Ignore generated files.
+	* AgilityPack.dll, api-style.css, ChangeLog, check, check-coverage, 
+	  convert.cs, current-api, deploy, documented, exdoc, ignore, 
+	  mono-api-metadata.html, monoapi.source, produce-lists, public, 
+	  public-api, README, sources, toc.xml, TODO, wapi: Copy from
+	  ../mono/docscripts.
+	* exdoc: Use the in-tree mono program to run convert.exe.
+	* Makefile.am: Mention files to clean/distribute; extract
+	  documentation (with exdoc) and then assemble documentation (with
+	  monoapi.make's assemble target) for use by monodoc.
+	* monoapi.make: Added; Makefile to use mcs' buid/rules.make to compile
+	  convert.cs and assemble documentation.  (This is a separate file so
+	  that we can include mcs' build/rules.make, which needs topdir set to
+	  behave properly BUT must be $(mcs_topdir) from Makefile.am's
+	  perspective.)
+	* monoapi.source: Add a /monodoc/node element for use with monodoc 2.2.
+
+2006-11-19  Miguel de Icaza  <[email protected]>
+
+	* exdoc: Move to use CSS instead of tables, this will break
+	GtkHTML rendering.
+
+	* ignore: Updated with more hidden APIs.
+
+	* Bunch of documentation work.
+

docs/Makefile.am

@@ -1,14 +1,33 @@
+sourcesdir = $(prefix)/lib/monodoc/sources
+
+sources_DATA = \
+	monoapi.source \
+	$(ASSEMBLED_DOCS)
+
+ASSEMBLED_DOCS = \
+	monoapi.tree monoapi.zip
+
 EXTRA_DIST = \
 	abc-removal.txt		\
+	AgilityPack.dll		\
 	aot-compiler.txt	\
+	api-style.css		\
 	assembly-bundle		\
+	check			\
+	check-coverage		\
+	convert.cs		\
+	current-api		\
+	deploy			\
+	documented		\
 	embedded-api		\
 	exception-handling.txt	\
 	exceptions		\
+	exdoc			\
 	file-share-modes	\
 	gc-issues		\
 	gc-variables-in-c	\
 	glossary.txt		\
+	ignore			\
 	internal-calls		\
 	ir-desc			\
 	jit-imt			\
@@ -19,17 +38,56 @@ EXTRA_DIST = \
 	magic.diff		\
 	mini-doc.txt		\
 	mini-porting.txt	\
+	mono-api-metadata.html	\
 	mono_handle_d		\
+	monoapi.make		\
+	monoapi.source		\
 	new-regalloc		\
 	object-layout		\
 	opcode-decomp.txt	\
 	precise-gc		\
+	produce-lists		\
+	public			\
+	public-api		\
+	README			\
 	release-notes-1.0.html	\
 	remoting		\
 	ssapre.txt		\
 	stack-alignment		\
 	stack-overflow.txt	\
-	threading		\
 	thread-safety.txt	\
+	threading		\
+	toc.xml			\
+	TODO			\
 	tree-mover.txt		\
 	unmanaged-calls	
+
+dist-hook:
+	$(mkdir_p)  $(distdir)/sources
+	$(mkdir_p)  $(distdir)/svgs
+	cp sources/*  $(distdir)/sources
+	cp svgs/*     $(distdir)/svgs
+
+CLEANFILES = \
+	convert.exe* \
+	deploy/.stamp \
+	$(wildcard deploy/*) \
+	$(ASSEMBLED_DOCS)
+
+clean-local:
+	-rm -Rf html
+
+monoapi.tree monoapi.zip: monoapi.make Makefile.am toc.xml deploy/.stamp
+	cp api-style.css deploy
+	$(MAKE) -f $< topdir=$(mcs_topdir) assemble
+
+deploy/.stamp: convert.exe Makefile.am
+	$(mkdir_p) html
+	perl exdoc -h . ../mono/*/*.c
+	touch $@
+
+extract : deply/.stamp
+
+convert.exe: monoapi.make convert.cs Makefile.am
+	$(MAKE) -f $< topdir=$(mcs_topdir) convert.exe
+

docs/README

@@ -0,0 +1,81 @@
+* 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.
+

docs/TODO

@@ -0,0 +1,37 @@
+* Methods that should be static, but I cant commit now because of other patches:
+
+	mono_class_set_failure
+	mono_class_get_nullable_param
+	mono_assembly_loaded_full
+
+* Methods that might need to be static, but am not sure:
+	mono_assembly_loaded_full
+	mono_image_loaded_by_guid_full
+	mono_image_loaded_full
+
+* Namespacing
+
+	Do we need to re-namespace the published helper_ routines to avoid
+ 	poluting the namespace?
+
+		helper_compile_generic_method
+		helper_ldstr
+		helper_ldstr_mscorlib
+		helper_newobj_mscorlib
+		helper_stelem_ref
+		helper_stelem_ref_check
+
+* Need to make public:
+
+	If the mono_mb_ interface is public, we need to make public:
+
+	MonoWrapperType
+	MonoDefaults.
+
+* Generate a table of contents at the begining of each page for APIs.
+
+* Fill in with a concept guide
+
+* Install documentation into monodoc's standard location.
+
+* Add support for inserting "api:" nodes into the index in the Monodoc XHTML provider.

docs/api-style.css

@@ -0,0 +1,40 @@
+   h3 { 
+       font-size: 18px;
+       padding-bottom: 4pt;
+       border-bottom: 2px solid #dddddd;
+   }
+
+   .api {
+     border: 1px solid;
+     padding: 10pt;
+     margin: 10pt;
+   } 
+
+   .api-entry { 
+       border-bottom: none;
+       font-size: 18px;
+   }
+
+   .prototype {
+     border: 1px solid;
+     background-color: #f2f2f2;
+     padding: 5pt;
+     margin-top: 5pt;
+     margin-bottom: 5pt;  
+   } 
+
+   .header {
+     border: 1px solid;
+     padding: 0 0 5pt 5pt;
+     margin: 10pt;
+     white-space: pre;
+       font-family: monospace;
+   }
+
+   .code {
+     border: 1px solid;
+     padding: 0 0 5pt 5pt;
+     margin: 10pt;
+     white-space: pre;
+       font-family: monospace;
+   }

docs/check

@@ -0,0 +1,15 @@
+#!/bin/sh
+dir=`dirname $0`
+
+for file in $*; 
+do
+	perl $dir/exdoc $file | grep ^Function:  | sed -e 's/Function: //' -e 's/://' > documented
+	nm `dirname $file`/.libs/`basename $file .c`.o | grep ' T ' | sed 's/.* T //' > public
+	for i in `cat public | grep -v $dir/ignore`; do
+		if grep $i documented > /dev/null; then
+			true
+		else
+			echo $i is not documented | grep -v ves_icall
+		fi
+	done
+done

docs/check-coverage

@@ -0,0 +1,16 @@
+#!/bin/sh
+add_h4()
+{
+	sed -e 's,^\(.*\)$,<h4><a name="api:\1">\1</a></h4>,'
+}
+
+dir=`dirname $0`
+sh $dir/produce-lists || exit 1
+cat $dir/public-api $dir/wapi > $dir/current-api
+for i in `cat $dir/current-api`; do
+	if grep "api:$i" $dir/sources/mono-api-*.html > /dev/null; then
+		true;
+	else
+		echo "Missing: $i from the template";
+	fi
+done

docs/convert.cs

@@ -0,0 +1,12 @@
+using HtmlAgilityPack;
+
+class Convert {
+
+	static void Main (string [] args)
+	{
+		HtmlDocument doc = new HtmlDocument();
+		doc.Load(args [0]);
+		doc.OptionOutputAsXml = true;
+		doc.Save(args [1]);
+	}
+}