Documenting Model Elements

<< Click to Display Table of Contents >>

Navigation:  »No topics above this level«

Documenting Model Elements

Previous pageReturn to chapter overviewNext page

RepreZen API Studio includes special-purpose views for generated documentation and diagrams.  As we have seen with the Diagram View, these are updated automatically as you edit your rapidModel. The Documentation View can be found in the same area as the Diagram View we saw a the end of the this section. By default the RepreZen API Studio Perspective includes the Documentation View in the right-hand pane.

If you don't see the Documentation view where it should be, on the right hand side of the main window, do the following:

1.Click Window > Open Perspective > Other.
2.From the list select RepreZen and click OK:
The Documentation tab is added to the right View pane (as above).

If you go to the documentation for TaxFilingObject and scroll down you'll see there are empty columns for documentation text:

You can fill these in by adding documentation elements to the RAPID model.

In RepreZen™ API Studio, most model elements can be documented with a preceding documentation comment, in the following format:


/** [documentation] */


Comments may also span multiple lines.

/** [documentation] 



Documenting the API and Data Types

1. We'll document the data model first by adding the following red lines (or simply by copying the following code block, and pasting this over the current data model):
/** Supporting data types for the TaxBlaster API */
dataModel TaxBlasterDataModel
       /** A tax filing record for a given user, in a given tax jurisdiction, in a specified tax year. */
       structure TaxFiling
               /** A unique, system-assigned identifier for the tax filing. */
               filingID : string
               /** Reference to the person who owns this filing. */
               taxpayer : reference Person
               /** Country, province, state or local tax authority
                 where this is being filed.*/
               jurisdiction : string
               /** Tax year */
               year : gYear
               /** Period within the year, if any */
               period : int
               /** Currency code */
               currency : string
               /** Total income reported on tax filing. *
               grossIncome : decimal
               /** Net tax liability */
               taxLiability : decimal
       /** A TaxBlaster user. */
       structure Person
               /** A unique, system-assigned identifier for the user. */
               id : string
               /** Legal family name. */
               lastName : string
               /** Legal first name. */
               firstName : string
               /** Names previously used **/
               otherNames : string*
2.Now we'll add some documentation comments to the API Model, for example:
/** An individual Tax Filing record, accessed by its ID */
objectResource TaxFilingObject type TaxFiling
       URI taxfilings/{id}
               /** filingID of the requested TaxFiling */
               required templateParam id property filingID
       method GET getTaxFiling
               response TaxFilingObject statusCode 200
       method PUT putTaxFiling
               request TaxFilingObject
               response statusCode 200
               response statusCode 400
/** An individual user by ID. */
objectResource PersonObject type Person
       URI people/{id}
               /** id of the requested Person */
               required templateParam id property id
       method GET getPersonObject
               response PersonObject statusCode 200
       method PUT putPersonObject
               request PersonObject
               response statusCode 200
               response statusCode 400
3.Now, if we look at the Documentation View again, we should see the documentation text we just added:

Internal Code Comments

We may also want to comment the code itself, with text that should not be displayed in the generated documentation.  RepreZen API Studio supports single and multi-line comments in the following formats:

// [single-line or end-of-line comment]


/* [multi-line comment]




Copyright © 2016 ModelSolv, Inc.  All rights reserved. RepreZen and RAPID-ML are trademarks of ModelSolv, Inc. Swagger is a registered trademark of SmartBear Software, Inc. RepreZen API Studio is not associated with nor endorsed by SmartBear Software, Inc.