tools/monodoc/ChangeLog

   1 2010-04-25  Jonathan Pryor  <jpryor@novell.com>
   2
   3         * Monodoc/ecma-provider.cs: Support the full set of possible operator
   4           names within EcmaHelpSource.MakeOperatorSignature() (where "full" is
   5           "whatever is included in ECMA-335 §10.3.1 through §10.3.3").
   6           Fixes InvalidOperationException reported to mono-docs-list.
   7
   8 2010-02-28  Jonathan Pryor  <jpryor@novell.com>
   9
  10         * Monodoc/provider.cs: Add
  11           RootTree.LoadTree(string,string,IEnumerable) for compatibility with
  12           Mono 2.6's monodoc.dll.
  13
  14 2010-02-26  Jonathan Pryor  <jpryor@novell.com>
  15
  16         * Makefile: Add a System.Core.dll reference; embed monodoc.xml as a
  17           resource.
  18         * Monodoc/provider.cs: Add a
  19           RootTree.LoadTree(string,XmlDocument,IEnumerable<string>) method.
  20           This is so 'mdoc export-html-webdoc' doesn't need to rely on the
  21           system-wide .source files (allowing execution w/o changing/replacing
  22           the system-wide .source files) and so MonoDevelop can support
  23           multiple .source files spread throughout the system sanely.
  24         * Monodoc/ecma-provider.cs: Always add the extension methods contained
  25           in the current EcmaHelpSource, instead of implicitly requiring that
  26           the current EcmaHelpSource also be contained within
  27           RootTree.HelpSources.  This simplifies logic in 'mdoc'.
  28
  29 2010-01-13  Jonathan Pryor  <jpryor@novell.com>
  30
  31         * Monodoc/provider.cs, Monodoc/ecma-provider.cs: Improve cache support
  32           by having EcmaHelpSource.GetTextFromUrl() look for cached contents.
  33           This greatly speeds up type member listings (e.g. T:...List`1/*),
  34           e.g. from ~2.0s to 0.06s.
  35
  36 2010-01-13  Jonathan Pryor  <jpryor@novell.com>
  37
  38         * Mono.Documentation/XmlDocUtils.cs: XmlDocUtils.AddExtensionMethods()
  39           wasn't adding extension methods which matched *interfaces* of base
  40           classes.  Result: Mono.Options.OptionSet (which inherits
  41           System.Collections.ObjectModel.KeyedCollection`2 which inherits from
  42           System.Collections.ObjectModel.Collection`1 which implements
  43           System.Collections.Generic.IEnumerable`1) wasn't getting any of the
  44           LINQ extension methods (which is bad).  Fix this.
  45
  46 2010-01-13  Jonathan Pryor  <jpryor@novell.com>
  47
  48         * Resources/mdoc-html-utils.xsl: Fix regression caused by 2009-12-02
  49           commit adding GetLinkTargetHtml().  The problem was that when
  50           running within ASP.NET/monodoc ~all extension method links would be
  51           'javascript:alert("...")M:Foo.Method(...)', which is clearly wrong.
  52           This occurred because $linkid's generation would always call
  53           GetLinkTargetHtml() with a $cref value of '', thus the monodoc
  54           GetLinkTarget() would return '', so GetLinkTargetHtml() would return
  55           the javascript "not found" alert.  Thus, we can't expect
  56           GetLinkTargetHtml() with $cref='' to work under monodoc, but it's
  57           ~required to work sanely under 'mdoc export-html'.
  58           Solution is to not call GetLinkTargetHtml() here UNLESS we're doing
  59           'mdoc export-html' generation, which we assume to be the case if
  60           $html-anchor is true.
  61
  62 2009-12-30  Jonathan Pryor  <jpryor@novell.com>
  63
  64         * Lucene.Net/Lucene.Net/QueryParser/QueryParser.cs: Fix crash when
  65           searching for "()".  Fixes #423853.
  66           Thanks to Benoît Tuduri <bento78@gmail.com>.
  67
  68 2009-12-03  Jonathan Pryor  <jpryor@novell.com>
  69
  70         * Resources/mdoc-html-utils.xsl: Add support for generating namespace
  71           links via <see cref="N:..." />
  72
  73 2009-12-03  Jonathan Pryor  <jpryor@novell.com>
  74
  75         * Resources/mdoc-html-utils.xsl: Fix link-id generation of conversion
  76           operators.
  77
  78 2009-12-02  Jonathan Pryor  <jpryor@novell.com>
  79
  80         * Mono.Documentation/ManifestResourceResolver.cs:
  81           Assembly.GetManifestResourceStream() throws an exception if the
  82           resource isn't present (instead of returning null), so don't just
  83           call it to see if the resource exists.
  84         * Resources/mdoc-html-utils.xsl: .NET compatibility fixes (so that
  85           mdoc can run under .NET w/o bundling Mono's System.Xml):
  86           - Use msxsl:node-set() when required.
  87           - Use <xsl:variable/> not <xsl:param/> when a variable is needed.
  88           - Change semantics of GetLinkTarget(): instead of returning
  89             javascript code (previous behavior) or '--not-available--' (did
  90             this ever happen), return "" if the target can't be found.
  91           - Add GetLinkTargetHtml() to wrap GetLinkTarget() and return the
  92             previous javascript if the target couldn't be found.
  93
  94 2009-11-24  Jonathan Pryor  <jpryor@novell.com>
  95
  96         * Monodoc/ecma-provider.cs: Use XslCompiledTransform instead of
  97           XslTransform, as XslCompiledTransform is *significantly* faster
  98           under .NET (3m7s -> 1.7s for some tests).
  99
 100 2009-10-02  Jonathan Pryor  <jpryor@novell.com>
 101
 102         * Mono.Documentation/XmlDocUtils.cs: GetInterfaces() can throw if the
 103           type we're trying to load can't be found (e.g. if a type implements
 104           an internal interface, there won't be an XML file for that internal
 105           interface).  Ignore the exception.
 106
 107 2009-09-25  Jonathan Pryor  <jpryor@novell.com>
 108
 109         * Monodoc/ecma-provider.cs: Don't return 'null' from GetPublicUrl(),
 110           but instead provide a decent URL even if the url isn't to a single
 111           member, but instead to show all members, e.g. T:System.String/*.
 112         * Monodoc/provider.cs: Obsolete Node.URL.  It's too variable for sane
 113           use; use Node.PublicUrl.
 114
 115 2009-09-09  Jonathan Pryor  <jpryor@novell.com>
 116
 117         * Mono.Documentation/ManifestResourceResolver.cs: Allow it to lookup
 118           files located in multiple directories.  Needed so that 'mdoc
 119           export-html' can properly deal with multiple source directories.
 120
 121 2009-08-13  Jonathan Pryor  <jpryor@novell.com>
 122
 123         * Monodoc/provider.cs: Add a RootTree.AddSource(string) method, so that
 124           additional directories can be checked for .source file loading.
 125
 126 2009-08-13  Jonathan Pryor  <jpryor@novell.com>
 127
 128         * Monodoc/provider.cs: Make RootTree.LoadTree() just call
 129           RootTree.LoadTree(null), and move the .config-file parsing into
 130           .LoadTree(string) (for when basedir==null).  This will simplify the
 131           logic of monodoc, as we want to add the ability to monodoc to use
 132           any arbitrary directory, and this will remove the need to do
 133           `if (d==null) RootTree.LoadTree(); else RootTree.LoadTree(d)`.
 134           This also conforms to FxDG guidelines.
 135
 136 2009-08-12  Jonathan Pryor  <jpryor@novell.com>
 137
 138         * Resources/mdoc-html-format: Added; XSLT file to match
 139           "//format[@type='text/html']//*", to support "pass-through"
 140           semantics.  This allows you to use actual HTML within your
 141           documentation and have it visible to HTML-supporting output formats.
 142           WARNING: Use as a "last resort" -- this is primarily intended for
 143           importing existing HTML w/o needing lots of extra logic to convert
 144           into mdoc format XML first (with a corresponding loss of fidelity).
 145           However, it means that if (when) we get non-HTML output format
 146           support, the <format type="text/html" /> blocks WILL be skipped for
 147           that non-HTML output format.
 148
 149           For example, the forever-on-the-back-burner ROFF output support --
 150           to remove the use of lynx, as no one ever has it installed --
 151           wouldn't be able to support HTML format, so it would skip these
 152           <format type="text/html"/> blocks.
 153
 154           Consider <format /> the moral equivalent of Perl POD's
 155           '=begin formatname' block; see perlpod(1).
 156         * Resources/mdoc-html-utils.xsl: <xsl:import/> mdoc-html-format.xsl.
 157           It *must* be imported (NOT included) so that it will have a lower
 158           priority than other <template/>s, thus allowing the HTML formatter
 159           to <xsl:apply-templates/> which then use the "normal" rules.  This
 160           allows:
 161                 <format type="text/html">
 162                         <p><see cref="T:System.String" /></p>
 163                 </format>
 164           to work as expected.
 165         * Makefile: Add mdoc-html-format.xsl as a resource.
 166
 167 2009-04-16  Jonathan Pryor  <jpryor@novell.com>
 168
 169         * Monodoc/man-provider.cs: NEVER return a non-null string from
 170           HelpSource.GetText() unless *useful* content is being returned, as
 171           when non-null is returned RootTree.RenderUrl() assumes that the url
 172           was handled and won't try any other HelpSources.  In this case, we
 173           can (and do) have multiple ManHelpSources present, but since
 174           ManHelpSource.GetText() was returning "<html>url was null</html>",
 175           RootTree thought it was handled...when it wasn't.  Fix.
 176
 177 2009-04-16  Jonathan Pryor  <jpryor@novell.com>
 178
 179         * Monodoc/provider.cs: Overview: MonoDevelop loads monodoc.dll into
 180           it's own process, and spawns monodoc GUI into a separate process,
 181           then sends Node.URL values (obtained from the MonoDevelop process)
 182           to load the documentation into the monodoc GUI.  Problem:
 183           occasionally the requested documentation isn't loaded, but instead
 184           some completely unrelated documentation is shown instead.  This is
 185           because the Node.URL value contains HelpSource-dependent data, e.g.
 186           a Node.URL value of "ecma:0#Foo/" will specify the 1st file
 187           within...whatever HelpSource is first consulted by monodoc (which
 188           can vary between monodoc runs, the phase of the moon, etc.).
 189           Solution: Add a Node.PublicUrl property which returns _stable_ URLs
 190           which aren't specific to a given HelpSource.
 191           - Add Node.PublicUrl property, which delegates to
 192             Provider.GetPublicUrl(string), so that a Provider can generate a
 193             Provider-independent URL (if possible).
 194           - Print PublicUrl from Node.PrintTree().
 195           - Add RootTree.GetSupportedFormats(), RootTree.GetProvider()
 196             methods.
 197           - Make RootTree.GetHelpSource() public.
 198         * Monodoc/ecma-provider.cs: Add EcmaDoc.GetCref() method (generates an
 199           XML documentation //see/@cref value), override
 200           Provider.GetPublicUrl() (which will return cref's if possible).
 201
 202 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
 203
 204         * Monodoc/ecma-provider.cs: EcmaHelpSource.GetText() doesn't need to
 205           call GetCachedText() twice.
 206
 207 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
 208
 209         * Monodoc/provider.cs: Correct UseWebdocCache logic.
 210         * Monodoc/xhtml-provider.cs: Use GetCachedText().
 211
 212 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
 213
 214         * Monodoc/provider.cs: UseWebdocCache is a better name that
 215           IgnoreCache (considering that cache is disabled by default).
 216
 217 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
 218
 219         * Monodoc/provider.cs:
 220           - Add HelpSource.IgnoreCache field, so that if the cache is present
 221             it will be ignored.  (Required by 'mdoc export-html-webdoc' so it
 222             gets "fresh" content to generate the cache, and by monodoc GUI as
 223             it can't use the cache'd HTML; cache'd HTML is for ASP.NET
 224             webdoc only.)
 225           - Alter the cache directory from e.g. sources/netdocs to
 226             sources/cache/netdocs (as defined by
 227             XmlDocUtils.GetCacheDirectory()).
 228           - Add HelpSource.GetCachedText() method which will return the
 229             contents of the cache for an id.
 230         * Monodoc/addins-provider.cs, Monodoc/ecma-provider.cs,
 231           Monodoc/error-provider.cs, Monodoc/man-provider.cs,
 232           Monodoc/simple-provider.cs: Use GetCachedText().
 233         * Mono.Documentation/XmlDocUtils.cs: Add GetCacheDirectory(),
 234           GetCacheFileName() methods.
 235
 236 2009-04-14  Jonathan Pryor  <jpryor@novell.com>
 237
 238         * Monodoc/provider.cs: Fix NullReferenceException in 'mdoc dump-tree'.
 239
 240 2009-04-09 Gonzalo Paniagua Javier <gonzalo@novell.com>
 241
 242         * ecma-provider.cs: remove 'using'.
 243         * provider.cs: if there's a directory with the base name, read the
 244         files from there instead of from the .zip file.
 245
 246 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
 247
 248         * Monodoc/ecma-provider.cs: Viewing type members (plural, e.g. the
 249           Fields sub-node) would result in a stack overflow within
 250           Resources/mdoc-html-utils.xsl:GetInheritedMembers(), because the
 251           document() XSLT function was being used to obtain the base type's
 252           documentation.  It stack overflowed because the XmlUrlResolver was
 253           being used, which when given e.g. file:///DocAttribute.xml, would
 254           return file:///DocAttribute.xml (which makes sense), but it was
 255           non-terminating.  (I find this troubling as it should have been
 256           trying to resolve e.g. System.Attribute, not DocAttribute; it must
 257           be some XmlTransform-fu that was substituting documents.)
 258           The fix is for EcmaUncompiledHelpSource to provide an alternate
 259           document XmlResolver, one which always returns null from
 260           XmlResolver.ResolveUri(), thus preventing endless recursion.
 261
 262 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
 263
 264         * Mono.Documentation/XmlDocUtils.cs: It's possible for the `loader'
 265           delegate to return `null' if no further base types are found, so
 266           stop processing if we find a null base type.
 267         * Monodoc/provider.cs:
 268           - Make GetHelpStream() virtual so that EcmaUncompiledHelpSource can
 269             override it, as the default zip-based behavior is inappropriate.
 270           - Make GetHelpXmlWithChanges() virtual so that
 271             EcmaUncompiledHelpSource can override it, as the default zip-based
 272             behavior is inappropriate.
 273           - When initializing UncompiledHelpSources, set the
 274             HelpSource.RootTree property (avoids an NRE from
 275             EcmaHelpSource.GetTextFromUrl() when it reads RootTree.HelpSources).
 276         * Monodoc/ecma-provider.cs:
 277           - Within the XmlDocUtils.AddExtensionMethods() call, don't always
 278             prefix the type with "T:", as sometimes the type will already start
 279             with "T:", which is the case with EcmaUncompiledHelpSource ids.
 280           - Add EcmaUncompiledHelpSource.GetHelpStream() and
 281             EcmaUncompiledHelpSource.GetHelpXmlWithChanges(), which Do The
 282             Right Thing for the file-based backend.
 283
 284 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
 285
 286         * Monodoc/ecma-provider.cs: For some reason,
 287           EcmaHelpSource.GetNamespaceDocument() wasn't being used anymore,
 288           which is what EcmaUncompiledHelpSource overrides to permit loading
 289           of local files.  Result: an exception when trying to view namespaces
 290           of local (non-assembled) directories.  Oops.  "Fixes" 443508.
 291
 292 2009-02-26  Jonathan Pryor  <jonpryor@vt.edu>
 293
 294         * Monodoc/provider.cs: Revert; Don't check for Tree.Nodes == null, as it
 295           happens in numerous places.  Instead, take a page out of the "I
 296           never should have invented `null'" book, and ensure that Tree.Nodes
 297           can never be null.  This fixes the "HelpSource has 0 items" issue
 298           and several other related ones.
 299
 300 2009-02-26  Jonathan Pryor  <jonpryor@vt.edu>
 301
 302         * Monodoc/provider.cs: It's possible for a HelpSource to have 0
 303           elements (which can be done by e.g. running `mdoc assemble' on an
 304           empty directory), in which case HelpSource.Tree.Nodes will be null.
 305           Make sure that we don't get a NullReferenceException.
 306           Patch thanks to Theerud Lawtrakul.  Fixes #443699.
 307
 308 2009-02-25  Jonathan Pryor  <jonpryor@vt.edu>
 309
 310         * Makefile:
 311           - s/TEST_FILES/MAN_TEST_FILES/g: $(TEST_FILES) is used by the normal
 312             build process, so the local definition is lost (and thus ignored).
 313             Result: Test/* isn't actually copied.  Oops.  Changing to
 314             MAN_TEST_FILES allows things to be copied.
 315           - Fix the filenames within $(MAN_TEST_FILES) so `make dist-local'
 316             works without error.
 317           - Fixes #479753.
 318
 319 2009-02-09  Jonathan Pryor  <jonpryor@vt.edu>
 320
 321         * Makefile: Don't include mono-ecma-css.js as a resource.
 322         * Monodoc/ecma-provider.cs: Insert helper.js, not mono-ecma-css.js.
 323         * Monodoc/provider.cs: Surround the contents of `helper.js' with a
 324           <script/> block so that valid HTMl is generated.
 325         * Resources/helper.js: Remove <script/> block, so that `helper.js' is an
 326           actual JavaScript file, not an SGML file w/ JavaScript content.
 327         * Resources/mono-ecma-css.js: Remove; use Resources/helper.js instead.
 328
 329 2009-01-05  Jonathan Pryor  <jonpryor@vt.edu>
 330
 331         * Makefile: Fix $(the_lib) dependencies so that monodoc.dll is rebuilt
 332           when one of Resources/* is modified.
 333         * Resources/mdoc-html-utils.xsl: Rework the Requirements block so that
 334           it doesn't require //AssemblyInfo or //AssemblyVersion.  This allows
 335           `mdoc update -fno-assembly-versions ...`-produced XML to still
 336           produce HTML with a Requirements section (skipping the Assembly
 337           Versions block but generating the Namespace and Assembly blocks).
 338           Change the behavior of //since generation so that instead of
 339           printing out a note before the method summary, a Since block is added
 340           to the Requirements section, and the Since block contains the
 341           //since/@version text.  All this to make Mike Kestner happier. :-)
 342
 343 2008-10-29  Jonathan Pryor  <jonpryor@vt.edu>
 344
 345         * Monodoc/xhtml-provider.cs: Use HelpSource.Message(), not
 346           Console.WriteLine().
 347
 348 2008-10-28  Jonathan Pryor  <jonpryor@vt.edu>
 349
 350         * Monodoc/provider.cs: Add HelpSource.InlineCss and
 351           HelpSource.InlineJavaScript virtual properties, so that the help
 352           source can provide specific CSS and JavaScript to be included into
 353           the generated HTML document.  This is used by the ASP.NET front-end,
 354           as it needs to insert the CSS & JavaScript separately (as it also
 355           inserts its own CSS & JavaScript).
 356         * Monodoc/ecma-provider.cs, Monodoc/ecmaspec-provider.cs,
 357           Monodoc/error-provider.cs: Override InlineCss & InlineJavaScript, as
 358           appropriate.
 359
 360 2008-10-24  Jonathan Pryor  <jonpryor@vt.edu>
 361
 362         * Monodoc/addins-provider.cs, Monodoc/ecma-provider.cs,
 363           Monodoc/ecmaspec-provider.cs, Monodoc/error-provider.cs,
 364           Monodoc/man-provider.cs, Monodoc/monohb-provider.cs,
 365           Monodoc/provider.cs: Remove Console.WriteLine() spew; helps cleanup
 366           `make` output in mcs/docs (from `mdoc assemble`, which indirectly
 367           invokes most of the *-provider files).  We solve this problem by
 368           providing a TraceLevel-based message system, so that messages are
 369           only generated if they are less than or equal to the requested
 370           output level (thus skipping the more verbose "every file" messages
 371           from ecma-provider.cs & error-provider.cs).
 372         * provider.cs: Change Node.CompareTo() to use a "natural sorting"
 373           algorithm -- this allows the C# Language Specification nodes to
 374           continue being displayed in the correct order.
 375
 376 2008-10-21  Jonathan Pryor  <jonpryor@vt.edu>
 377
 378         * Monodoc/provider.cs:
 379           - Fix Node.Sort() so that it doesn't NRE if nodes == null.
 380           - Fix Node.CompareTo() so that it can sort Nodes that haven't been
 381             loaded yet.
 382           - Add "libraries" as an alias for "root", so that .source files can
 383             refer to the parent "libraries" (which would allow us to change
 384             the location of "libraries" in the future, should we want to).
 385           - If a /monodoc/source/@path refers to a nonexistant node, then
 386             insert the contents under Various instead of ignoring it.
 387           - Sort the top-level nodes.
 388           - Sort the `parent` node after inserting children under it.  This
 389             allows multiple different .source files to insert nodes under the
 390             same parent node and still have the child nodes sorted as most
 391             mortals would expect.
 392           - Support a //node/@parent attribute, which allows for creating
 393             nodes underneath the specified parent node.  This allows multiple
 394             different .source files to contribute to the tree and depend upon
 395             each other.  Thus, instead of having a single monodoc.xml file
 396             that needs to know the entire tree in advance, the entire tree can
 397             be spread across multiple .source files and filled at runtime.
 398
 399 2008-10-18  Jonathan Pryor  <jonpryor@vt.edu>
 400
 401         * Makefile $(LIBRARY_PACKAGE): Set to `monodoc`, as we historically
 402           have had a monodoc package (and thus should preserve it).
 403
 404 2008-10-17  Jonathan Pryor  <jonpryor@vt.edu>
 405
 406         * Makefile: Distribute monodoc.dll.config.in.
 407
 408 2008-10-17  Jonathan Pryor  <jonpryor@vt.edu>
 409
 410         * Makefile: Generate a monodoc.dll.config (installed by gacutil), so
 411           that monodoc.dll can find the documentation sources.
 412
 413 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 414
 415         * Mono.Documentation/ManifestResourceResolver.cs,
 416           Mono.Documentation/XmlDocUtils.cs: Make types public so that they
 417           can be used from ../mdoc/mdoc.exe.
 418
 419 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 420
 421         * Makefile: Update $(thisdir).
 422
 423 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 424
 425         * Assmbly/AssemblyInfo.cs: Change location of mono.snk (since the
 426           monodoc directory was moved from mcs/class to mcs/tools).
 427
 428 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 429
 430         * Makefile: Improve `make clean` support.
 431
 432 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 433
 434         * Makefile: Add EXTRA_DISTFILES; monodoc.dll should depend upon
 435           Makefile (in case the /resource: lines change); shorten the .gif
 436           resource names.
 437
 438 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 439
 440         * Test (svn:ignore): Ignore generated files.
 441         * Makefile: Add tests for man-provider.
 442
 443 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 444
 445         * ChangeLog: Added/Started.
 446         * Makefile: Added; build monodoc.dll.
 447