tools/monodoc/ChangeLog

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