tools/monodoc/ChangeLog

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