Introduction

E2E Builder provides several documentation features to support different kinds of users:

• modelers who want to modify the service and need a quick overview on the service's use cases, backend access and data structures
• service consumers who want to call the service and need information on the service interface
• Bridge operators who need a basic understanding of the service's purpose and features.

For these documentation purposes, E2E Builder offers the possibility to add documentation and comment tags to model elements.

How to Add a Documentation Tag

Lookup the element you want to add documentation to in the containment tree or diagram and open the specification dialog by right-clicking the element and selecting Specification from the context menu.

	Click Documentation/Hyperlinks and start typing in the documentation field.
	By checking HTML, you can also insert HTML formatted documentation.
	By clicking , you can open an advanced HTML editor that has more formatting options and also allows to edit the HTML directly.

How to Add Comment Tags

Lookup the element you want to add a comment to in the containment tree and select Create Element > Comment from the context menu. Simply start typing to add the comment. Comments can be plain text only.

Service Documentation for Modelers

To give modelers a good overview on the service we recommend to

• provide an overview on what the service does by drawing a use case diagram
• show the main data structures and relations by drawing a class diagram
• give an overview on the main backend processing by drawing a sequence diagram
• provide a change log in the xml file, if you are not using a version control system

Use Case Diagram

Draw a simple use case diagram describing the main actors and main processing in a package called e.g. Use Cases.

We also recommend to make the documentation that previously has been added to the Data package visible by adding it to this diagram.
You can do this as follows:

	Go to the specification dialog of the Data package and select the documentation element.
	Drag and drop it to the diagram pane.

You can define to not display stereotype <<documentation>> (like shown above) via the symbol properties from the context menu.

Sequence Diagram

Draw a sequence diagram to give an overview on the main backend processing.

Change Log

If you do not use a version control system, keep a change log table in package Use Cases, e.g. on a use case diagram called Change Log.

Class Diagram

Draw class diagrams for the main structures in dedicated packages (see Containment Tree Organization).

Service Documentation for Service Consumers

MagicDraw provides the possibility to add documentation and comment tags to model elements. Documentation and comment tags added to service model elements (service, operation, parameter) are explaining the service interface. They are meant to be read by the service consumer and will be generated to

• to the YAML file for REST services
  For more information see REST Interface Documentation and Tags.

• the WSDL file for SOAP services

  <?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="urn:GetTitleService"
                  xmlns:http="http://schemas.xmlsoap.org/soap/http"
                  xmlns:xs="http://www.w3.org/2001/XMLSchema"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
                  name="GetTitleService"
                  targetNamespace="urn:GetTitleService">
   <wsdl:documentation>Documentation of Service GetTitleService</wsdl:documentation>
   <wsdl:types/>
   <wsdl:message name="GetTitlePortType_getTitle_Request">
      <wsdl:part name="inputTitle" type="xs:string">
         <wsdl:documentation>&lt;html&gt;
  &lt;head&gt;
        &lt;style&gt;
            p {padding:0px; margin:0px;}
        &lt;/style&gt;
    &lt;/head&gt;
  &lt;body&gt;
    &lt;p&gt;
&lt;b&gt;&lt;span style="font-size:24pt;"&gt;HTML Documentation of Parameter in&lt;/span&gt;&lt;/b&gt;

    &lt;/p&gt;

&lt;/body&gt;
&lt;/html&gt;</wsdl:documentation>
         <wsdl:documentation>Comment of parameter in</wsdl:documentation>
      </wsdl:part>
   </wsdl:message>
   <wsdl:message name="GetTitlePortType_getTitle_Response">
      <wsdl:part name="outputTitle" type="xs:string"/>
   </wsdl:message>
   <wsdl:portType name="GetTitlePortType">
      <wsdl:documentation>The port type provides an operation to copy a string and convert it to upper case. That string is used as title in the client application.</wsdl:documentation>
      <wsdl:operation name="getTitle">
         <wsdl:documentation>The operation defines an interface to copy a simple string, convert it to upper case and return it to the client application.</wsdl:documentation>
         <wsdl:documentation>Comment on operation GetTitle</wsdl:documentation>
         <wsdl:input message="tns:GetTitlePortType_getTitle_Request"/>
         <wsdl:output message="tns:GetTitlePortType_getTitle_Response"/>
      </wsdl:operation>
   </wsdl:portType>
   <wsdl:binding name="GetTitlePortType_SOAPBinding" type="tns:GetTitlePortType">
      <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
      <wsdl:operation name="getTitle">
         <soap:operation soapAction=""/>
         <wsdl:input>
            <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                       namespace="urn:Services.GetTitleService.Ports.GetTitlePortType"
                       use="encoded"/>
         </wsdl:input>
         <wsdl:output>
            <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                       namespace="urn:Services.GetTitleService.Ports.GetTitlePortType"
                       use="encoded"/>
         </wsdl:output>
      </wsdl:operation>
   </wsdl:binding>
   <wsdl:service name="GetTitleService">
      <wsdl:documentation>Documentation of Service GetTitleService</wsdl:documentation>
      <wsdl:documentation>Comment on Service GetTitlService</wsdl:documentation>
      <wsdl:port binding="tns:GetTitlePortType_SOAPBinding" name="GetTitlePortType">
         <soap:address location="http://${wsdl_host_urn:Component_View.Composites.EducationLesson1.GetTitleService}:10011/GetTitleService/GetTitlePortType"/>
      </wsdl:port>
   </wsdl:service>
</wsdl:definitions>

Service Documentation for Bridge Operators

Like with all other model elements, you can also add documentation to the Data package. This documentation will be available for reading and editing on the E2E Bridge.
See Documentation of an xUML Service for more information on that feature.