| Age | Commit message (Collapse) | Author |
|---|
|
|
|
When a type overrides a member in one framework, but does not in another framework
processed after the first, the Member node was being removed, even though the entry
remained in teh first framework index file. This Resolves #39
|
|
If a framework has a different inheritance chain, another `Base/BaseTypeName`
element will be added with a `FrameworkAlternate` attribute.
Resolves #16
|
|
Fixes #32, which was an issue with the ascii null character. It caused the resulting XML to be
malformed.
|
|
A MemberGroup can be intermixed amongst the other Member nodes.
It will be sorted to be in front of the other similarly named Members.
It must contain a MemberName attribute, and can have: Docs, and AssemblyInfo nodes.
Resolves #35
|
|
mdoc now supports documenting multiple frameworks. You can use this new functionality by passing the path to a configuration file in the `-frameworks` (or `-fx` for short) parameter.
```
mdoc update -o path/to/documentationXML -frameworks path/to/frameworks.xml
```
This command will result in one XML file per framework in the `path/to/documentationXML/FrameworksIndex` folder.
``` xml
<?xml version="1.0" encoding="utf-8"?>
<Framework Name="Two">
<Namespace Name="MyFramework.MyOtherNamespace">
<Type Name="MyFramework.MyOtherNamespace.MyOtherClass" Id="T:MyFramework.MyOtherNamespace.MyOtherClass">
<Member Id="M:MyFramework.MyOtherNamespace.MyOtherClass.#ctor" />
...
</Type>
</Namespace>
</Framework>
```
Configuration File
This is a sample configuration file:
``` xml
<?xml version="1.0" encoding="utf-8"?>
<Frameworks>
<Framework Name="One" Source="One">
<assemblySearchPath>dependencies/One</assemblySearchPath>
</Framework>
<Framework Name="Two" Source="Two">
<assemblySearchPath>dependencies/Two</assemblySearchPath>
</Framework>
</Frameworks>
```
Note that the `assemblySearchPath` is meant to house dependent assemblies that mono.cecil must be able to resolve. You can have as many as you need for each framework if you happen to have them separated into multiple folders. Also the `-L` parameter applies globally to every framework.
Frameworks Config Bootstrap
To simplify the tedium of creating the configuration file, a simple command was added that will use the folder structure to create a basic configuration file:
``` csharp
mdoc fx-bootstrap path/to/frameworks
```
This will create a file at `path/to/frameworks/frameworks.xml`, using the folders in `path/to/frameworks` as the names/paths
DocId Signatures
You can now pass a flag to add a `DocId` signature to every `Type` and `Member` node.
```
mdoc update -o out/path some.dll -use-docid
```
_please note_: framework index files will _always_ use the DocId as their identifiers.
Frameworks Index files Grouped by Namespace
Framework index files now have types grouped by namespace. Example:
``` xml
<?xml version="1.0" encoding="utf-8"?>
<Framework Name="Two">
<Namespace Name="MyFramework.MyOtherNamespace">
<Type Name="MyFramework.MyOtherNamespace.MyOtherClass" Id="T:MyFramework.MyOtherNamespace.MyOtherClass">
<Member Id="M:MyFramework.MyOtherNamespace.MyOtherClass.#ctor" />
...
</Type>
</Namespace>
</Framework>
```
Bug Fixes and Enhancements
- Resolves #13
- Resolves #27
- Resolves #31
- Resolves #33
|
|
These files were inadvertently left out of PRs that were merged to master
|
|
Closes #6
|
|
In some cases, for example when running in "frameworks" mode (ie. https://github.com/mono/api-doc-tools/pull/18), you might have non-managed .dlls in the directory. This change allows mdoc to simply write the fact that it couldn't load the assembly, and continue doing work.
Resolves #7
Potentially provides a temporary workaround for #8, #9
|
|
[mdoc] Extension method crash fix, removes -multiassembly
|
|
This was inadvertently removed in https://github.com/mono/mono/commit/611a43ee0f672adbac3e25dc77731843a3d10cf1 from MulticastDelegate.CombineImpl().
Add the type check back in the Delegate base class, we already do the same in Remove().
Add unit tests to cover the behavior to the corlib test suite. (reverted from commit f29878dc713f4e148fe0a1e703fae8929e6fb6e0)
Needed to update some monodoc tests to match that an exception is now thrown again.
|
|
[mdoc] Added -api-style parameter.
|
|
[mdoc] Improved error handling for multiassembly.
|
|
|
|
The new `multiassembly` option lets you run `mdoc update` on assemblies that
contain the same types. This can come into play when you have a set of assemblies
that run on different platforms, with a slightly differing API surface area on
each platform (for example: tvOS, watchOS, iOS); in this case you can maintain
all of the documentation in a single set of XML documents.
With this option enabled, an `AssemblyInfo` node will be added for every assembly
that a type is found in, in addition to every member. While this may seem verbose,
it's really the only way to capture the information about what assemblies a given
type or member can be found in.
|
|
|
|
In supplement of the changes submitted in 09b97cba2e7c2d9c68830d55ff3d99c5f36eb439, there were
some additional edge cases that were not originally considered, and so this patch resolves these
additional issues. In particular, there was a bug in the `RemoveApiStyle` method that wasn't
checking the value of the `apistyle` attribute before removing it. This caused members to be
stripped of apistyle inadvertently.
There was an issue in the type removal code that caused
too many files to be removed. This patch adds additional checks to make sure that a file isn't
going to be removed if it contains members in the other style that shoulnd't be removed
Finally, there was an issue that arose after the aforementioned changes in the `OrderTypeAttributes`
method. It was somewhat counterintuitive, but it wasn't allowing the reordering of attributes
with the `.Remove` method (throwing an exception). Not entirely sure why this was happening,
but using the `.RemoveNamedItem` method worked around the issue.
|
|
Specifically, when updating classic and unified assemblies, members
that were completely removed from one or both assemblies were not
being removed from the XML. This patch updates mdoc's `DeleteMember`
method to properly handle deletion in all scenarios (normal, classic, unified).
Of course, deletion will still not happen if one of two things is true:
- `--delete` is *not* passed into the `mdoc update` call and the member node
contains existing documentation.
- `--preserve` *is* passed into the `mdoc update` invocation.
In both of those cases, the member will not be deleted, and a message stating
as such will be written as a warning to the output.
|
|
This enum, which can be found in Xamarin's iOS and Mac products use a custom encoding
scheme which resulted in invalid values being shown when processed with mdoc. This patch
adds a special case to watch for this particular enumeration value, and decodes the data
correctly.
Additionally, the code that formats the values for flags enumerations was refactored. Future extensibility of this feature can now be done by simply implementing a new `FlagsFormatter`, and applying the proper logic in the `MakeAttributesValueString` function.
|
|
|
|
The existing update was not doing a good job of matching members that have both generic and non-generic members. So for example, if you had a method, `Foo<T>`, and added a non-generic version in a future update (`Foo`); you could end up with a situation where one of the members was being duplicated.
|
|
|
|
(The error message is actually created by ourselves.)
|
|
With referencesource, the XmlReader now requires the DTD in SYSTEM
declaration to exist. So just add the DTD.
|
|
|
|
|
|
|
|
|
|
recent XML changes
The XML work in 661430fd1f052c5589bcd5d116f37b9ee4e27210 and bf39f5aec034800abcfe5e73a63ddd1414cb8078 changed the whitespace handling, so the mdoc test suite failed.
Refreshing the files makes them identical to what MS.NET produces and fixes the mdoc tests.
|
|
https://bugzilla.xamarin.com/show_bug.cgi?id=18411
If a class explicitly implements an internal interface, those members will no
longer be documented, nor will the interface show up in the class' signature.
This allows for a library to hide internal implementation details that an end
user would not be able to take advantage of (ie. can't cast to internal
interface to call methods).
Includes test (check-monodocer-internal-interface) added to makefile.
|
|
|
|
secondary assembly that doesn't drop the specified namespace
|
|
|
|
(Reported by directhex on #mono 2014-05-14 at 14:28 EDT.)
When importing Microsoft XML Documentation, if a //altmember/@name,
//exception/@name, or //permission/@name attribute is encountered then
mdoc will die with a NullReferenceException:
mdoc: System.NullReferenceException: Object reference not set to an instance of an object
at Mono.Documentation.MsxdocDocumentationImporter.ImportDocumentation (Mono.Documentation.DocsNodeInfo info)
at Mono.Documentation.MDocUpdater.MakeDocNode (Mono.Documentation.DocsNodeInfo info)
at Mono.Documentation.MDocUpdater.UpdateMember (Mono.Documentation.DocsNodeInfo info)
at Mono.Documentation.MDocUpdater.MakeMember (System.Xml.XmlDocument doc, Mono.Documentation.DocsNodeInfo info)
at Mono.Documentation.MDocUpdater.DoUpdateType2 (System.String message, System.Xml.XmlDocument basefile, Mono.Cecil.TypeDefinition type, System.String output, Boolean insertSince)
at Mono.Documentation.MDocUpdater.StubType (Mono.Cecil.TypeDefinition type, System.String output)
at Mono.Documentation.MDocUpdater.DoUpdateType (Mono.Cecil.TypeDefinition type, System.String basepath, System.String dest)
at Mono.Documentation.MDocUpdater.DoUpdateAssembly (Mono.Cecil.AssemblyDefinition assembly, System.Xml.XmlElement index_types, System.String source, System.String dest, System.Collections.Generic.HashSet`1 goodfiles)
at Mono.Documentation.MDocUpdater.DoUpdateAssemblies (System.String source, System.String dest)
at Mono.Documentation.MDocUpdater.Run (IEnumerable`1 args)
at Mono.Documentation.MDoc.Run (System.String[] args)
at Mono.Documentation.MDoc.Main (System.String[] args)
The cause of the NullReferenceException is due to inconsistent
checking: we check that _either_ `child.Attributes["cref"]` OR
`child.Attributes["name"]` is not null, and if one of them IS non-null
then we just grab `child.Attributes["cref"].Value`, which will throw a
NullReferenceException if the @name attribute was present but not the
@cref attribute.
The fix is to be consistent: once we grab an XmlAttribute, use the
already looked up XmlAttribute, don't re-look it up.
|
|
|
|
|
|
|
|
|
|
|
|
Commit 0a2c38df changed Delegate.Remove() so that it uses
Locale.GetText(), which thus introduces additional exceptions which
can be possibly thrown from Delegate.Remove().
This is similar to the situation in corlib/3d3fe6af (added
Locale.GetText() use) and mdoc/574dbc8e (updated unit tests).
|
|
|
|
|
|
3d3fe6af (among other commits...) "broke" the `mdoc` unit tests, as it
did two things:
1. It added a new codepath calling string.Format(), thus introducing
a new set of exceptions.
2. Due to an `mdoc` bug, (1) resulted in a stack overflow on OS X.
(1) demonstrates that the mdoc unit tests might be too brittle.
(2) was fixed in 04bf9ad.
The problem with 04bf9ad, though, is that it resulted in a gigantic
~212MB diff, because while the recursion was "fixed", we could still
process the same method multiple times, resulting in _lots_ of
duplication, e.g. System.String.get_Chars() would be repeated hundreds
of times for a given exception.
Improve the source reporting mechanism so that instead of a
List<MemberReference> we use a HashSet<MemberReference>, listing each
source location _once_ instead of repeating them.
The _formatting_ of the <exception/> element is also changed so that
each source location is on its own line, making it easier to read and
review the locations.
|
|
Commit 44b2b4a8 completely broke `mdoc export-msxdoc` because
EcmaDoc.GetCref() was removed. Expected:
<member name="C:Mono.DocTest.DocAttribute(System.String)">
Actual:
<member name="Mono.DocTest.DocAttribute..ctor">
i.e. useless.
The fix: bring back GetCref(), this time within monodocs2slashdoc.cs.
Commit 0ad6ffde changed the HTML-generating stylesheet and moved some
@id attributes around, thus breaking the mdoc unit tests (expected
output likewise changed). Fix the monodoc XSLTs so that we don't emit
id="" attributes (id's with no value).
Update mdoc's expected output so that tests pass[*].
[*]: tests will NOT actually pass, as 04bf9add -- attempted fix for
an OS X stackoverflow caused by 3d3fe6af -- results in a gigantic
216MB diff because String.get_Chars() is repeated over and over and
over... The updated expected output in this commit is the "ideal"
update needed after locally reverting 3d3fe6af and 04bf9add.)
|
|
Nested `protected` types are accessible from subclasses, and thus
should be documented just as `public` nested types are.
|
|
|
|
|
|
`mdoc update --delete` is supposed to remove XML for types and type
members that are no longer present. This works sanely if the
type/member has only one assembly version in it, but once a member is
found in multiple versions, --delete only removes for the assembly
version currently being processed, and thus the member may stay in.
Ordinarily this is sufficient, and is why the HTML output lists the
assembly versions the type/member is found in.
However, then we introduce -fno-assembly-versions, which removes the
version store (if present) and doesn't re-generate. Thus, when both
are present, we would expect types and members to be removed,
irregardless of any pre-existing version information (because that
version information will be removed). This didn't happen. Worse,
because we kept re-processing version information, we'd ~never remove
any members even after repeated invocations, because we weren't
properly skipping the version store. Oops.
Fix the interaction, and Add tests so we ensure this works.
|
|
Consider the method `void M(double[,,])`. When attempting to import
documentation for this method, `mdoc-update` should generate the CREF
"M(System.Double[0:,0:,0:])", otherwise some documentation isn't imported.
Due to this (and `mcs /doc`-related fixes) and other changes, flush the
expected output as more docs are properly imported.
|
|
Several commits changed `mdoc` output without committing the updated
output, thus causing `make run-test` to fail, e.g. commit
9a1075956e25969118930caff352ad7d3ecc9655.
Flush the expected output so that `make run-test` is useful.
|
