|
<< Click to Display Table of Contents >> Documenting Model Elements |
  
|
|
<< Click to Display Table of Contents >> Documenting Model Elements |
|
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]
[continued...]
*/
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 mediaTypes application/xml method GET getTaxFiling request 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 mediaTypes application/xml method GET getPersonObject request 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]
[continued...]
*/
| 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. |