[mapguide-commits] r6222 - in trunk/Tools/Maestro: Doc
Maestro.Editors Maestro.Editors/Packaging Maestro.Packaging
OSGeo.MapGuide.ExtendedObjectModels OSGeo.MapGuide.MaestroAPI
OSGeo.MapGuide.MaestroAPI/Commands
OSGeo.MapGuide.MaestroAPI/CoordinateSystem
OSGeo.MapGuide.MaestroAPI/CrossConnection
OSGeo.MapGuide.MaestroAPI/Feature OSGeo.MapGuide.MaestroAPI/Mapping
OSGeo.MapGuide.MaestroAPI/ObjectModels
OSGeo.MapGuide.MaestroAPI/Resource/Conversion
OSGeo.MapGuide.MaestroAPI/Resource/Validation
OSGeo.MapGuide.MaestroAPI/Services
svn_mapguide at osgeo.org
svn_mapguide at osgeo.org
Sat Nov 12 11:07:10 EST 2011
Author: jng
Date: 2011-11-12 08:07:10 -0800 (Sat, 12 Nov 2011)
New Revision: 6222
Added:
trunk/Tools/Maestro/Maestro.Editors/Packaging/NsDoc.cs
Modified:
trunk/Tools/Maestro/Doc/MaestroAPI.shfbproj
trunk/Tools/Maestro/Maestro.Editors/Maestro.Editors.csproj
trunk/Tools/Maestro/Maestro.Packaging/PackageBuilder.cs
trunk/Tools/Maestro/Maestro.Packaging/ResourceDataItem.cs
trunk/Tools/Maestro/OSGeo.MapGuide.ExtendedObjectModels/ModelSetup.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Commands/IGetFdoCacheInfo.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Commands/IGetResourceContents.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/ConnectionProviderRegistry.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/CoordinateSystem/ICoordinateSystemCatalog.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/CrossConnection/ResourceMigrator.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Feature/IFeatureReader.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Feature/IReader.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/IServerConnection.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Mapping/MapSelection.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Mapping/RuntimeMap.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/ObjectModels/LoadProcedureInterfaces.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Conversion/IResourceConverter.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Conversion/NsDoc.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Validation/NsDoc.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IDrawingService.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IFeatureService.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IFusionService.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IMappingService.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IResourceService.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/ISiteService.cs
trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/ITileService.cs
Log:
#1319: API documentation updates
Modified: trunk/Tools/Maestro/Doc/MaestroAPI.shfbproj
===================================================================
--- trunk/Tools/Maestro/Doc/MaestroAPI.shfbproj 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/Doc/MaestroAPI.shfbproj 2011-11-12 16:07:10 UTC (rev 6222)
@@ -40,21 +40,20 @@
<VisibleItems>Attributes, InheritedMembers, Protected, SealedProtected</VisibleItems>
<ApiFilter>
<Filter entryType="Namespace" fullName="Maestro.Editors.FeatureSource.Preview" isExposed="False" />
- <Filter entryType="Namespace" fullName="Maestro.Editors.FeatureSource.Providers.Odbc" isExposed="False" />
- <Filter entryType="Namespace" fullName="Maestro.Editors.FeatureSource.Providers.Odbc.Drivers" isExposed="False" />
- <Filter entryType="Namespace" fullName="Maestro.Editors.FeatureSource.Providers.Wms" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.ApplicationDefinition_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.DrawingSource_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.FeatureSource_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.LayerDefinition_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.LoadProcedure_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.MapDefinition_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.PrintLayout_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.SymbolDefinition_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.SymbolLibrary_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.WebLayout_1_0_0" isExposed="False" />
- <Filter entryType="Namespace" fullName="System.Runtime.CompilerServices" isExposed="False" />
- </ApiFilter>
+<Filter entryType="Namespace" fullName="Maestro.Editors.FeatureSource.Providers.Odbc" isExposed="False" />
+<Filter entryType="Namespace" fullName="Maestro.Editors.FeatureSource.Providers.Odbc.Drivers" isExposed="False" />
+<Filter entryType="Namespace" fullName="Maestro.Editors.LayerDefinition.Vector.Scales" isExposed="False" />
+<Filter entryType="Namespace" fullName="Maestro.Editors.LayerDefinition.Vector.StyleEditors" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.ApplicationDefinition_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.DrawingSource_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.FeatureSource_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.LayerDefinition_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.LoadProcedure_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.MapDefinition_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.PrintLayout_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.SymbolDefinition_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.SymbolLibrary_1_0_0" isExposed="False" />
+<Filter entryType="Namespace" fullName="OSGeo.MapGuide.ObjectModels.WebLayout_1_0_0" isExposed="False" /></ApiFilter>
<SdkLinkType>None</SdkLinkType>
<FeedbackEMailAddress>jumpinjackie at gmail.com</FeedbackEMailAddress>
<WebsiteSdkLinkType>None</WebsiteSdkLinkType>
Modified: trunk/Tools/Maestro/Maestro.Editors/Maestro.Editors.csproj
===================================================================
--- trunk/Tools/Maestro/Maestro.Editors/Maestro.Editors.csproj 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/Maestro.Editors/Maestro.Editors.csproj 2011-11-12 16:07:10 UTC (rev 6222)
@@ -905,6 +905,7 @@
<Compile Include="Packaging\EditResourceDataEntryDialog.designer.cs">
<DependentUpon>EditResourceDataEntryDialog.cs</DependentUpon>
</Compile>
+ <Compile Include="Packaging\NsDoc.cs" />
<Compile Include="Packaging\PackageEditorDialog.cs">
<SubType>Form</SubType>
</Compile>
Copied: trunk/Tools/Maestro/Maestro.Editors/Packaging/NsDoc.cs (from rev 6220, trunk/Tools/Maestro/Maestro.Editors/MapDefinition/NsDoc.cs)
===================================================================
--- trunk/Tools/Maestro/Maestro.Editors/Packaging/NsDoc.cs (rev 0)
+++ trunk/Tools/Maestro/Maestro.Editors/Packaging/NsDoc.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -0,0 +1,35 @@
+#region Disclaimer / License
+// Copyright (C) 2011, Jackie Ng
+// http://trac.osgeo.org/mapguide/wiki/maestro, jumpinjackie at gmail.com
+//
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Lesser General Public
+// License as published by the Free Software Foundation; either
+// version 2.1 of the License, or (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+//
+#endregion
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Runtime.CompilerServices;
+
+namespace Maestro.Editors.Packaging
+{
+ /// <summary>
+ /// The <c>Maestro.Editors.Packaging</c> namespace provides UI components for
+ /// editing MapGuide Package files
+ /// </summary>
+ [CompilerGenerated]
+ class NamespaceDoc
+ {
+ }
+}
Modified: trunk/Tools/Maestro/Maestro.Packaging/PackageBuilder.cs
===================================================================
--- trunk/Tools/Maestro/Maestro.Packaging/PackageBuilder.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/Maestro.Packaging/PackageBuilder.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -1128,7 +1128,7 @@
}
/// <summary>
- /// Base calss of all package operations
+ /// Base class of all package operations
/// </summary>
public abstract class PackageOperation
{
Modified: trunk/Tools/Maestro/Maestro.Packaging/ResourceDataItem.cs
===================================================================
--- trunk/Tools/Maestro/Maestro.Packaging/ResourceDataItem.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/Maestro.Packaging/ResourceDataItem.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -24,7 +24,7 @@
namespace Maestro.Packaging
{
/// <summary>
- /// Represents a data item on a resource
+ /// Represents a resource data item from a package
/// </summary>
public class ResourceDataItem
{
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.ExtendedObjectModels/ModelSetup.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.ExtendedObjectModels/ModelSetup.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.ExtendedObjectModels/ModelSetup.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -52,7 +52,7 @@
///
/// </summary>
[CompilerGenerated]
- public class NsDoc { }
+ class NsDoc { }
public static class ModelSetup
{
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Commands/IGetFdoCacheInfo.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Commands/IGetFdoCacheInfo.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Commands/IGetFdoCacheInfo.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -28,6 +28,18 @@
/// <summary>
/// Defines the command for querying the cache status of FDO connections
/// </summary>
+ /// <example>
+ /// This example shows how invoke the <see cref="T:OSGeo.MapGuide.MaestroAPI.Commands.IGetFdoCacheInfo"/>
+ /// command. Note that you should check if the connection supports this command through its capabilities
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection conn;
+ /// ...
+ /// IGetFdoCacheInfo command = (IGetFdoCacheInfo)conn.CreateCommand(CommandType.GetFdoCacheInfo);
+ /// FdoCacheInfo cacheInfo = command.Execute();
+ /// ]]>
+ /// </code>
+ /// </example>
public interface IGetFdoCacheInfo : ICommand
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Commands/IGetResourceContents.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Commands/IGetResourceContents.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Commands/IGetResourceContents.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -27,6 +27,26 @@
/// <summary>
/// Defines a command to get a set of resource contents in a single batch
/// </summary>
+ /// <example>
+ /// This example shows how invoke the <see cref="T:OSGeo.MapGuide.MaestroAPI.Commands.IGetResourceContents"/>
+ /// command. Note that you should check if the connection supports this command through its capabilities
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection conn;
+ /// ...
+ /// IGetResourceContents command = (IGetResourceContents)conn.CreateCommand(CommandType.GetResourceContents);
+ /// string [] resourceIds = new string[] {
+ /// "Library://Samples/Sheboygan/Layers/Parcels.LayerDefinition",
+ /// "Library://Samples/Sheboygan/Layers/Rail.LayerDefinition",
+ /// "Library://Samples/Sheboygan/Layers/HydrographicPolygons.LayerDefinition",
+ /// "Library://Samples/Sheboygan/Layers/CityLimits.LayerDefinition",
+ /// "Library://Samples/Sheboygan/Layers/Buildings.LayerDefinition",
+ /// "Library://Samples/Sheboygan/Layers/Roads.LayerDefinition"
+ /// };
+ /// Dictionary<string, IResource> results = command.Execute(resourceIds);
+ /// ]]>
+ /// </code>
+ /// </example>
public interface IGetResourceContents : ICommand
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/ConnectionProviderRegistry.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/ConnectionProviderRegistry.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/ConnectionProviderRegistry.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -72,21 +72,26 @@
public delegate IServerConnection ConnectionFactoryMethod(NameValueCollection initParams);
/// <summary>
+ /// <para>
/// The entry point of the Maestro API. The <see cref="ConnectionProviderRegistry"/> is used to create <see cref="IServerConnection"/>
/// objects. <see cref="IServerConnection"/> is the root object of the Maestro API, and is where most of the functionality provided
/// by this API is accessed from.
- ///
+ /// </para>
+ /// <para>
/// The <see cref="ConnectionProviderRegistry"/> supports dynamic creation of <see cref="IServerConnection"/> objects given a provider name
/// and a connection string, which specifies the initialization parameters of the connection. The connection providers are defined in an XML
/// file called ConnectionProviders.xml which contains all the registered providers. Each provider has the following properties:
- ///
- /// 1. The name of the provider
- /// 2. The assembly containing the <see cref="IServerConnection"/> implementation
- /// 3. The name of this <see cref="IServerConnection"/> implementation.
- ///
+ /// </para>
+ /// <list type="number">
+ /// <item><description>The name of the provider</description></item>
+ /// <item><description>The assembly containing the <see cref="IServerConnection"/> implementation</description></item>
+ /// <item><description>The name of this <see cref="IServerConnection"/> implementation</description></item>
+ /// </list>
+ /// <para>
/// The <see cref="IServerConnection"/> implementation is expected to have a non-public constructor which takes a single parameter,
/// a <see cref="System.Collections.Specialized.NameValueCollection"/> containing the initialization parameters parsed from the given connection
/// string.
+ /// </para>
/// </summary>
/// <example>
/// This example shows how to create a http-based MapGuide Server connection to the server's mapagent interface.
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/CoordinateSystem/ICoordinateSystemCatalog.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/CoordinateSystem/ICoordinateSystemCatalog.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/CoordinateSystem/ICoordinateSystemCatalog.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -23,6 +23,30 @@
/// <summary>
/// Defines a coordinate system catalog
/// </summary>
+ /// <example>
+ /// This example uses the <see cref="T:OSGeo.MapGuide.MaestroAPI.CoordinateSystem.ICoordindateSystemCatalog"/>
+ /// to create a simple coordinate system transformation to transform points.
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection conn;
+ /// ...
+ /// ICoordinateSystemCatalog csCatalog = conn.CoordinateSystemCatalog;
+ /// //Find the source and target coordinate system definitions
+ /// CoordinateSystemDefinitionBase srcCs = csCatalog.FindCoordSys("LL84");
+ /// CoordinateSystemDefinitionBase dstCs = csCatalog.FindCoordSys("WGS84.PseudoMercator");
+ /// //Create the transform using the WKTs of the source and target coordinate system definitions
+ /// ISimpleTransform trans = csCatalog.CreateTransform(srcCs.WKT, dstCs.WKT);
+ ///
+ /// double x = -71.061342;
+ /// double y = 42.355892;
+ /// double tx;
+ /// double ty;
+ ///
+ /// trans.Transform(x, y, out tx, out ty);
+ /// //tx and ty will contain the transformed coordinates
+ /// ]]>
+ /// </code>
+ /// </example>
public interface ICoordinateSystemCatalog
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/CrossConnection/ResourceMigrator.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/CrossConnection/ResourceMigrator.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/CrossConnection/ResourceMigrator.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -30,6 +30,39 @@
/// A helper class that copies/moves resources from one
/// connection to another
/// </summary>
+ /// <example>
+ /// This example shows how to copy resources from one connection to another using
+ /// the <see cref="T:OSGeo.MapGuide.MaestroAPI.CrossConnection.ResourceMigrator"/> class
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection sourceConn;
+ /// IServerConnection targetConn;
+ /// ...
+ /// ResourceMigrator migrator = new ResourceMigrator(sourceConn, targetConn);
+ /// //These are the source resource ids to copy
+ /// string [] sourceIds = new string[] {
+ /// "Library://Samples/Sheboyan/Data/Parcels.FeatureSource",
+ /// "Library://Samples/Sheboyan/Data/Rail.FeatureSource",
+ /// "Library://Samples/Sheboyan/Data/Islands.FeatureSource",
+ /// "Library://Samples/Sheboyan/Data/Buildings.FeatureSource"
+ /// };
+ /// //These the the target ids we are copying to. The number of source and
+ /// //target ids must be the same
+ /// string [] targetIds = new string[] {
+ /// "Library://Production/Data/Parcels.FeatureSource",
+ /// "Library://Production/Data/Rail.FeatureSource",
+ /// "Library://Production/Data/Islands.FeatureSource",
+ /// "Library://Production/Data/Buildings.FeatureSource"
+ /// };
+ /// //Set up the re-base options. This is generally the common parent of the source and target ids.
+ /// //This is to ensure that any resource ids references are updated as they are copied across
+ /// RebaseOptions options = new RebaseOptions("Library://Samples/Sheboygan/", "Library://Production/");
+ /// bool bOverwrite = true;
+ /// //Execute the migration
+ /// string [] copied = migrator.CopyResources(sourceIds, targetIds, bOverwrite, options, null);
+ /// ]]>
+ /// </code>
+ /// </example>
public class ResourceMigrator
{
private IServerConnection _source;
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Feature/IFeatureReader.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Feature/IFeatureReader.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Feature/IFeatureReader.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -28,6 +28,13 @@
/// Provides a forward-only, read-only iterator
/// for reading features selected from a feature source
/// </summary>
+ /// <remarks>
+ /// <list type="bullet">
+ /// <item><description>You must call <see cref="M:ReadNext"/> before you can access the data</description></item>
+ /// <item><description>For each property, determine the property type and then call the appropriate Get<type>() method to get the value of the property.</description></item>
+ /// <item><description>The exception for this is if you are access the value via the indexer. In this case you only need determine the property type when casting from the System.Object that is returned by the indexer</description></item>
+ /// </list>
+ /// </remarks>
public interface IFeatureReader : IReader, IFeature, IEnumerable<IFeature>
{
@@ -36,6 +43,12 @@
/// <summary>
/// Provides access to the property values within each feature for a <see cref="T:OSGeo.MapGuide.MaestroAPI.Feature.IFeatureReader"/>
/// </summary>
+ /// <remarks>
+ /// <list type="bullet">
+ /// <item><description>For each property, determine the property type and then call the appropriate Get<type>() method to get the value of the property.</description></item>
+ /// <item><description>The exception for this is if you are access the value via the indexer. In this case you only need determine the property type when casting from the System.Object that is returned by the indexer</description></item>
+ /// </list>
+ /// </remarks>
public interface IFeature : IRecord
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Feature/IReader.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Feature/IReader.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Feature/IReader.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -28,6 +28,13 @@
/// Provides a forward-only, read-only iterator for reading data. You must call <see cref="ReadNext"/>
/// before you can access any data
/// </summary>
+ /// <remarks>
+ /// <list type="bullet">
+ /// <item><description>You must call <see cref="M:ReadNext"/> before you can access the data</description></item>
+ /// <item><description>For each property, determine the property type and then call the appropriate Get<type>() method to get the value of the property.</description></item>
+ /// <item><description>The exception for this is if you are access the value via the indexer. In this case you only need determine the property type when casting from the System.Object that is returned by the indexer</description></item>
+ /// </list>
+ /// </remarks>
public interface IReader : IDisposable, IRecord
{
/// <summary>
@@ -98,6 +105,12 @@
/// <summary>
/// Provides access to the property values within each result for a <see cref="T:OSGeo.MapGuide.MaestroAPI.Feature.IReader"/>
/// </summary>
+ /// <remarks>
+ /// <list type="bullet">
+ /// <item><description>For each property, determine the property type and then call the appropriate Get<type>() method to get the value of the property.</description></item>
+ /// <item><description>The exception for this is if you are access the value via the indexer. In this case you only need determine the property type when casting from the System.Object that is returned by the indexer</description></item>
+ /// </list>
+ /// </remarks>
public interface IRecord
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/IServerConnection.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/IServerConnection.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/IServerConnection.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -29,11 +29,14 @@
namespace OSGeo.MapGuide.MaestroAPI
{
/// <summary>
+ /// <para>
/// MapGuide Platform connection interface. This is the root object of the Maestro API which typically
/// represents a session with a MapGuide Server. Connections are created through the
/// <see cref="T:OSGeo.MapGuide.MaestroAPI.ConnectionProviderRegistry"/> class.
- ///
+ /// </para>
+ /// <para>
/// All implementations supports the base services of the MapGuide Geospatial API:
+ /// </para>
/// <list type="bullet">
/// <item>
/// <description>Resource Service (<see cref="T:OSGeo.MapGuide.MaestroAPI.Services.IResourceService"/>) for manipulation of repositories and resources</description>
@@ -45,10 +48,11 @@
/// <description>Coordinate System Catalog (<see cref="T:OSGeo.MapGuide.MaestroAPI.CoordinateSystem.ICoordinateSystemCatalog"/> for querying coordinate systems and for translating WKT, cs code and EPSG codes to other forms</description>
/// </item>
/// </list>
- ///
+ /// <para>
/// Additional services are supported at various levels depending on the implementation.
/// The <see cref="P:OSGeo.MapGuide.MaestroAPI.IServerConnection.Capabilities"/> property provides information about
/// what features, services and resource types are not supported.
+ /// </para>
/// </summary>
public interface IServerConnection
{
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Mapping/MapSelection.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Mapping/MapSelection.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Mapping/MapSelection.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -10,6 +10,68 @@
/// <summary>
/// Represents a map selection
/// </summary>
+ /// <example>
+ /// This sample shows how to list selected features in ASP.net. The sample expects 3 parameters:
+ /// <list type="number">
+ /// <item><description>The session ID (SESSION)</description></item>
+ /// <item><description>The runtime map name (MAPNAME)</description></item>
+ /// <item><description>The selection XML (SELECTION)</description></item>
+ /// </list>
+ /// <code>
+ /// <![CDATA[
+ /// string agent = "http://localhost/mapguide/mapagent/mapagent.fcgi";
+ /// IServerConnection conn = ConnectionProviderRegistry.CreateConnection(
+ /// "Maestro.Http",
+ /// "Url", agent,
+ /// "SessionId", Request.Params["SESSION"]);
+ ///
+ /// IMappingService mpSvc = (IMappingService)conn.GetService((int)ServiceType.Mapping);
+ /// string rtMapId = "Session:" + conn.SessionID + "//" + Request.Params["MAPNAME"] + ".Map";
+ /// RuntimeMap rtMap = mpSvc.OpenMap(rtMapId);
+ ///
+ /// string xml = Request.Params["SELECTION"];
+ /// //The map selection contains one or more layer selections
+ /// //each containing a one or more sets of identity property values
+ /// //(because a feature may have multiple identity properties)
+ ///
+ /// MapSelection selection = new MapSelection(rtMap, System.Web.HttpUtility.UrlDecode(xml));
+ /// if (selection.Count > 0)
+ /// {
+ /// StringBuilder sb = new StringBuilder();
+ /// for (int i = 0; i < selection.Count; i++)
+ /// {
+ /// MapSelection.LayerSelection layerSel = selection[i];
+ /// sb.Append("<p>Layer: " + layerSel.Layer.Name + " (" + layerSel.Count + " selected item)");
+ /// sb.Append("<table>");
+ /// for (int j = 0; j < layerSel.Count; j++)
+ /// {
+ /// sb.Append("<tr>");
+ /// object[] values = layerSel[j];
+ /// for (int k = 0; k < values.Length; k++)
+ /// {
+ /// sb.Append("<td>");
+ /// sb.Append(values[k].ToString());
+ /// sb.Append("</td>");
+ /// }
+ /// sb.AppendFormat("<td><a href='FeatureInfo.aspx?MAPNAME={0}&SESSION={1}&LAYERID={2}&ID={3}'>More Info</a></td>",
+ /// rtMap.Name,
+ /// conn.SessionID,
+ /// layerSel.Layer.ObjectId,
+ /// System.Web.HttpUtility.UrlEncode(layerSel.EncodeIDString(values)));
+ /// sb.Append("</tr>");
+ /// }
+ /// sb.Append("</table>");
+ /// Response.WriteLine("<p>Showing IDs of selected features</p>");
+ /// Response.WriteLine(sb.ToString());
+ /// }
+ /// }
+ /// else
+ /// {
+ /// Response.WriteLine("Nothing selected. Select some features first then run this sample again.");
+ /// }
+ /// ]]>
+ /// </code>
+ /// </example>
public class MapSelection : IBinarySerializable, IList<MapSelection.LayerSelection>
{
private RuntimeMap _map;
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Mapping/RuntimeMap.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Mapping/RuntimeMap.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Mapping/RuntimeMap.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -39,21 +39,25 @@
/// Represents a runtime instance of a Map Definition
/// </summary>
/// <remarks>
+ /// <para>
/// If you want to use this instance with the Rendering Service APIs, it is important to set the correct
/// meters per unit value before calling the <see cref="T:OSGeo.MapGuide.MaestroAPI.Mapping.RuntimeMap.Save"/> method, as an incorrect meters
/// per unit value will produce incorrect images.
- ///
+ /// </para>
+ /// <para>
/// Also note that to improve the creation performance, certain implementations of <see cref="T:OSGeo.MapGuide.MaestroAPI.IServerConnection"/>
/// offer a <see cref="T:OSGeo.MapGuide.MaestroAPI.Mapping.IRuntimeMapSetup"/> helper to return a series of layer definitions in a batch (fetching
/// layer definitions one at a time is the main performance bottleneck for large maps), batching can improve creation times by:
- ///
- /// - HTTP: 2x
- /// - Local: 3x (if using MapGuide 2.2 APIs. As this takes advantage of the GetResourceContents() API introduced in 2.2). For older versions of MapGuide there is no batching.
- ///
+ /// </para>
+ /// <list type="bullet">
+ /// <item><description>HTTP: 2x</description></item>
+ /// <item><description>Local: 3x (if using MapGuide 2.2 APIs. As this takes advantage of the GetResourceContents() API introduced in 2.2). For older versions of MapGuide there is no batching.</description></item>
+ /// </list>
+ /// <para>
/// In particular, the HTTP implementation of <see cref="T:OSGeo.MapGuide.MaestroAPI.IServerConection"/> uses the <see cref="T:System.Threading.ThreadPool"/>
/// class to fetch multiple layer definitions in parallel. If your code uses this implementation, be aware of this face and the performance implications
/// involved, as an excessively large thread pool size may negatively affect stability of your MapGuide Server.
- ///
+ /// </para>
/// </remarks>
/// <example>
/// How to create a <see cref="RuntimeMap"/> with the correct meters per unit value using the MgCoordinateSystem API
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/ObjectModels/LoadProcedureInterfaces.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/ObjectModels/LoadProcedureInterfaces.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/ObjectModels/LoadProcedureInterfaces.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -276,6 +276,12 @@
/// <summary>
/// A SDF load procedure. Execution is supported with limitations
/// </summary>
+ /// <remarks>
+ /// The SDF Load Procedure has the following limitations when executed by Maestro
+ /// <list type="bullet">
+ /// <item><description>The input SDF files must be SDF3 files. Loading of SDF2 files is not supported</description></item>
+ /// </list>
+ /// </remarks>
public interface ISdfLoadProcedure : IBaseLoadProcedure
{
/// <summary>
@@ -292,6 +298,13 @@
/// <summary>
/// A SHP load procedure. Execution is supported with limitations
/// </summary>
+ /// <remarks>
+ /// The SHP Load Procedure has the following limitations when executed by Maestro
+ /// <list type="bullet">
+ /// <item><description>Generalization is not supported</description></item>
+ /// <item><description>Conversion to SDF is not supported</description></item>
+ /// </list>
+ /// </remarks>
public interface IShpLoadProcedure : IBaseLoadProcedure
{
/// <summary>
@@ -308,6 +321,13 @@
/// <summary>
/// A SQLite load procedure. Execution is supported with limitations
/// </summary>
+ /// <remarks>
+ /// <para>SQLite load procedures can only be saved to a server whose site version is 2.2 or higher</para>
+ /// <para>The SQLite Load Procedure has the following limitations when executed by Maestro</para>
+ /// <list type="bullet">
+ /// <item><description>Generalization is not supported</description></item>
+ /// </list>
+ /// </remarks>
public interface ISqliteLoadProcedure : IBaseLoadProcedure
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Conversion/IResourceConverter.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Conversion/IResourceConverter.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Conversion/IResourceConverter.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -41,6 +41,22 @@
/// <summary>
/// Performs schematic upgrades of resources
/// </summary>
+ /// <example>
+ /// This example shows how to convert a given Layer Definition to a specific version
+ /// <code>
+ /// <![CDATA[
+ /// ILayerDefinition layerDef;
+ /// ...
+ /// IResourceConverter converter = new ResourceObjectConverter();
+ /// ILayerDefinition converted = converter.Convert(layerDef, new Version(2, 3, 0));
+ ///
+ /// Version convertedVersion = converted.ResourceVersion;
+ /// // convertedVersion.Major == 2
+ /// // convertedVersion.Minor == 3
+ /// // convertedVersion.Build == 0
+ /// ]]>
+ /// </code>
+ /// </example>
public class ResourceObjectConverter : IResourceConverter
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Conversion/NsDoc.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Conversion/NsDoc.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Conversion/NsDoc.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -27,8 +27,6 @@
/// <summary>
/// The <c>OSGeo.MapGuide.MaestroAPI.Resource.Conversion</c> namespace provides classes and interfaces for
/// upgrading resources to newer versions.
- ///
- /// <remarks>The classes and interfaces in this namespace are subject to change at any time</remarks>
/// </summary>
[CompilerGenerated]
class NamespaceDoc
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Validation/NsDoc.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Validation/NsDoc.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Resource/Validation/NsDoc.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -26,7 +26,7 @@
{
/// <summary>
/// The <c>OSGeo.MapGuide.MaestroAPI.Resource.Validation</c> namespace provides classes for validating resources
- /// for common issues.
+ /// for common issues. The <see cref="T:OSGeo.MapGuide.MaestroAPI.Resource.Validation.ResourceValidatorSet"/> class provides the ability to validate resources
/// </summary>
[CompilerGenerated]
class NamespaceDoc
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IDrawingService.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IDrawingService.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IDrawingService.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -27,6 +27,17 @@
/// <summary>
/// Allows low level access to DWF (Design Web Format) data stored in a resource repository as part of a drawing source.
/// </summary>
+ /// <example>
+ /// This example shows how to obtain a drawing service instance. Note that you should check if this service type is
+ /// supported through its capabilities.
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection conn;
+ /// ...
+ /// IDrawingService drawingSvc = (IDrawingService)conn.GetService((int)ServiceType.Drawing);
+ /// ]]>
+ /// </code>
+ /// </example>
public interface IDrawingService : IService
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IFeatureService.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IFeatureService.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IFeatureService.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -30,6 +30,11 @@
/// <summary>
/// Provides services for accessing, querying and inspecting feature sources
/// </summary>
+ /// <remarks>
+ /// Note that <see cref="T:OSGeo.MapGuide.MaestroAPI.IServerConnection"/> provides
+ /// built-in access to resource and feature services. Using the <see cref="M:OSGeo.MapGuide.MaestroAPI.IServerConnection.GetService"/>
+ /// method is not necessary
+ /// </remarks>
public interface IFeatureService : IService
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IFusionService.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IFusionService.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IFusionService.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -27,6 +27,17 @@
/// <summary>
/// Provides services for the construction of Fusion web applications
/// </summary>
+ /// <example>
+ /// This example shows how to obtain a fusion service instance. Note that you should check if this service type is
+ /// supported through its capabilities.
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection conn;
+ /// ...
+ /// IFusionService fusionSvc = (IFusionService)conn.GetService((int)ServiceType.Fusion);
+ /// ]]>
+ /// </code>
+ /// </example>
public interface IFusionService : IService
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IMappingService.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IMappingService.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IMappingService.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -29,6 +29,17 @@
/// <summary>
/// Provides services for interaction with the runtime map
/// </summary>
+ /// <example>
+ /// This example shows how to obtain a mapping service instance. Note that you should check if this service type is
+ /// supported through its capabilities.
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection conn;
+ /// ...
+ /// IMappingService mappingSvc = (IMappingService)conn.GetService((int)ServiceType.Mapping);
+ /// ]]>
+ /// </code>
+ /// </example>
public interface IMappingService : IService
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IResourceService.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IResourceService.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/IResourceService.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -30,6 +30,11 @@
/// <summary>
/// Provides services for accessing resources in a repository
/// </summary>
+ /// <remarks>
+ /// Note that <see cref="T:OSGeo.MapGuide.MaestroAPI.IServerConnection"/> provides
+ /// built-in access to resource and feature services. Using the <see cref="M:OSGeo.MapGuide.MaestroAPI.IServerConnection.GetService"/>
+ /// method is not necessary
+ /// </remarks>
public interface IResourceService : IService
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/ISiteService.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/ISiteService.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/ISiteService.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -27,6 +27,17 @@
/// <summary>
/// Service interface for site operations
/// </summary>
+ /// <example>
+ /// This example shows how to obtain a site service instance. Note that you should check if this service type is
+ /// supported through its capabilities.
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection conn;
+ /// ...
+ /// ISiteService siteSvc = (ISiteService)conn.GetService((int)ServiceType.Site);
+ /// ]]>
+ /// </code>
+ /// </example>
public interface ISiteService : IService
{
/// <summary>
Modified: trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/ITileService.cs
===================================================================
--- trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/ITileService.cs 2011-11-11 17:21:14 UTC (rev 6221)
+++ trunk/Tools/Maestro/OSGeo.MapGuide.MaestroAPI/Services/ITileService.cs 2011-11-12 16:07:10 UTC (rev 6222)
@@ -26,6 +26,17 @@
/// <summary>
/// Provides services for map tile generation
/// </summary>
+ /// <example>
+ /// This example shows how to obtain a tile service instance. Note that you should check if this service type is
+ /// supported through its capabilities.
+ /// <code>
+ /// <![CDATA[
+ /// IServerConnection conn;
+ /// ...
+ /// ITileService tileSvc = (ITileService)conn.GetService((int)ServiceType.Tile);
+ /// ]]>
+ /// </code>
+ /// </example>
public interface ITileService : IService
{
/// <summary>
More information about the mapguide-commits
mailing list