2010-06-21 Atsushi Enomoto <atsushi@ximian.com>
[mcs.git] / tools / monodoc / ChangeLog
blobd144be0d63a604894213a404295b9bbc5e5e5e2c
1 2010-06-11  Jonathan Pryor  <jpryor@novell.com>
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.
14 2010-04-25  Jonathan Pryor  <jpryor@novell.com>
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.
21 2010-02-28  Jonathan Pryor  <jpryor@novell.com>
23         * Monodoc/provider.cs: Add
24           RootTree.LoadTree(string,string,IEnumerable) for compatibility with
25           Mono 2.6's monodoc.dll.
27 2010-02-26  Jonathan Pryor  <jpryor@novell.com>
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'.
42 2010-01-13  Jonathan Pryor  <jpryor@novell.com>
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.
49 2010-01-13  Jonathan Pryor  <jpryor@novell.com>
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.
59 2010-01-13  Jonathan Pryor  <jpryor@novell.com>
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.
75 2009-12-30  Jonathan Pryor  <jpryor@novell.com>
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>.
81 2009-12-03  Jonathan Pryor  <jpryor@novell.com>
83         * Resources/mdoc-html-utils.xsl: Add support for generating namespace
84           links via <see cref="N:..." />
86 2009-12-03  Jonathan Pryor  <jpryor@novell.com>
88         * Resources/mdoc-html-utils.xsl: Fix link-id generation of conversion
89           operators.
91 2009-12-02  Jonathan Pryor  <jpryor@novell.com>
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.
107 2009-11-24  Jonathan Pryor  <jpryor@novell.com>
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).
113 2009-10-02  Jonathan Pryor  <jpryor@novell.com>
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.
120 2009-09-25  Jonathan Pryor  <jpryor@novell.com>
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.
128 2009-09-09  Jonathan Pryor  <jpryor@novell.com>
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.
134 2009-08-13  Jonathan Pryor  <jpryor@novell.com>
136         * Monodoc/provider.cs: Add a RootTree.AddSource(string) method, so that 
137           additional directories can be checked for .source file loading.
139 2009-08-13  Jonathan Pryor  <jpryor@novell.com>
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.
149 2009-08-12  Jonathan Pryor  <jpryor@novell.com>
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.
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.
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.
180 2009-04-16  Jonathan Pryor  <jpryor@novell.com>
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.
190 2009-04-16  Jonathan Pryor  <jpryor@novell.com>
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).
215 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
217         * Monodoc/ecma-provider.cs: EcmaHelpSource.GetText() doesn't need to
218           call GetCachedText() twice.
220 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
222         * Monodoc/provider.cs: Correct UseWebdocCache logic.
223         * Monodoc/xhtml-provider.cs: Use GetCachedText().
225 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
227         * Monodoc/provider.cs: UseWebdocCache is a better name that
228           IgnoreCache (considering that cache is disabled by default).
230 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
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.
249 2009-04-14  Jonathan Pryor  <jpryor@novell.com>
251         * Monodoc/provider.cs: Fix NullReferenceException in 'mdoc dump-tree'.
253 2009-04-09 Gonzalo Paniagua Javier <gonzalo@novell.com>
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.
259 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
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.
275 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
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.
297 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
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.
305 2009-02-26  Jonathan Pryor  <jonpryor@vt.edu>
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.
313 2009-02-26  Jonathan Pryor  <jonpryor@vt.edu>
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.
321 2009-02-25  Jonathan Pryor  <jonpryor@vt.edu>
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.
332 2009-02-09  Jonathan Pryor  <jonpryor@vt.edu>
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.
342 2009-01-05  Jonathan Pryor  <jonpryor@vt.edu>
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. :-)
356 2008-10-29  Jonathan Pryor  <jonpryor@vt.edu>
358         * Monodoc/xhtml-provider.cs: Use HelpSource.Message(), not 
359           Console.WriteLine().
361 2008-10-28  Jonathan Pryor  <jonpryor@vt.edu>
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.
373 2008-10-24  Jonathan Pryor  <jonpryor@vt.edu>
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.
389 2008-10-21  Jonathan Pryor  <jonpryor@vt.edu>
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.
412 2008-10-18  Jonathan Pryor  <jonpryor@vt.edu>
414         * Makefile $(LIBRARY_PACKAGE): Set to `monodoc`, as we historically
415           have had a monodoc package (and thus should preserve it).
417 2008-10-17  Jonathan Pryor  <jonpryor@vt.edu>
419         * Makefile: Distribute monodoc.dll.config.in.
421 2008-10-17  Jonathan Pryor  <jonpryor@vt.edu>
423         * Makefile: Generate a monodoc.dll.config (installed by gacutil), so
424           that monodoc.dll can find the documentation sources.
426 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
428         * Mono.Documentation/ManifestResourceResolver.cs, 
429           Mono.Documentation/XmlDocUtils.cs: Make types public so that they
430           can be used from ../mdoc/mdoc.exe.
432 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
434         * Makefile: Update $(thisdir).
436 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
438         * Assmbly/AssemblyInfo.cs: Change location of mono.snk (since the 
439           monodoc directory was moved from mcs/class to mcs/tools).
441 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
443         * Makefile: Improve `make clean` support.
445 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
447         * Makefile: Add EXTRA_DISTFILES; monodoc.dll should depend upon
448           Makefile (in case the /resource: lines change); shorten the .gif
449           resource names.
451 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
453         * Test (svn:ignore): Ignore generated files.
454         * Makefile: Add tests for man-provider.
456 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
458         * ChangeLog: Added/Started.
459         * Makefile: Added; build monodoc.dll.