Home > Documentation, Templates > Generate a documentation of your model using CodeFluent API

Generate a documentation of your model using CodeFluent API


As a CodeFluent Entities architect, you may wonder how you could generate a human readable document of your model without having to write it manually. The answer is to use the CodeFluent template engine. This article gives you some basic understanding of how to write a template to generate a Rich Text File document (containing formatting, logo, etc) and also provide a ready to use template that you can customize according to your own needs.

All projects developed with CodeFluent Entities are based on models. A model is always composed of a set of entities. These entities contain properties, methods, rules, etc. In order to provide to people outside of the development team, an explanation of the CodeFluent model in a formatted document could be appreciated. To generate this document, a developer can use the template associated with this article. Nevertheless, the CodeFluent Entities model must be enriched with the desired documentation using CodeFluent Entities Messages with a dedicated attribute. This attribute is available at entity, property and method levels. Here’s a simplified sample model:

<cf:entity name="Customer">
  <cf:message class="_doc">Simple customer</cf:message>
  <cf:property name="Id">
    <cf:message class="_doc">Technical identifier</cf:message>
  </cf:property>
  <cf:property name="Phone">
    <cf:message class="_doc">Phone number of the customer</cf:message>
  </cf:property>
  <cf:method name="LoadByPhoneNumber" body="load(Phone) where Phone = @Phone">
    <cf:message class="_doc">Load customer by phone number</cf:message>
  </cf:method>
</cf:entity>

By the way, after generation, the properties and methods of the generated business object layer (BOM) will contain new tags in standard .NET format as illustrated hereafter:

Entity level

/// Customer entity
public partial class Customer

Property level

/// Phone number of the customer
public string Phone
{
  get { return this._phone; }
  set
  {
    this._phone = value;
    this.EntityState = CodeFluent.Runtime.CodeFluentEntityState.Modified;
    this.OnPropertyChanged(new System.ComponentModel.PropertyChangedEventArgs(“Phone”));
  }
}

Method level

/// Load customer by phone number
public static System.Data.IDataReader PageDataLoadByPhoneNumber(CodeFluent.Runtime.PageOptions pageOptions, string phone)

Using CodeFluent Entities’ template engine, we developed a template to generate a full documentation. Note that the CodeFluent Entities Template Producer supports text files format such as RTF files. To describe our example, we created a RTF file named [Template]Model documentation.rtf with Microsoft Word. We then edited our template and added some code using CodeFluent Entities API.

Let’s quickly describe the template inside:

  • First, retrieve all entities of the model:
    CultureInfo currentCulture = new CultureInfo(1033);
    Message messageGlobal = entity.GetMessage(“_doc”, currentCulture);
  • And do the same for methods and properties:
    CultureInfo culture = new CultureInfo(1033);
    IList properties = new List();
    IList methods = new List();
    
    foreach (Property property in entity.Properties)
    {
      Message messageProperty = property.GetMessage(“_doc”, currentCulture);
      if (messageProperty != null)
        properties.Add(property);
    }
    
    foreach (Method method in entity.Methods)
    {
      Message messageMethods = method.GetMessage(“_doc”, currentCulture);
      if (messageMethods != null)
        methods.Add(method);
    }

You can notice that we use the english culture (1033) but you can localize your documentation using “cultureName” attribute inside your model. For example, if you want to translate your comment into french, proceed as follows:

<cf:message class="_doc" cultureName="fr">Entité client</cf:message>

Then, you can get the message value:

[%foreach (Property property in properties) { Message currentMessage = property.GetMessage("_doc", currentCulture);%] [%= currentMessage.Value %] [%}%]

Let’s have a look at the generated RTF document:

How to use the provided template?

Put your template file into a directory of your choice and use the “template producer” in your project in order to produce the output documentation file:

<cf:producer name="Template Producer" typeName="CodeFluent.Producers.CodeDom.TemplateProducer, CodeFluent.Producers.CodeDom">
  <configuration sourceDirectory="Templates\Doc"
         targetDirectory=".\Generated\"
         outputEncoding="iso-8859-1"/>
</cf:producer>

We hope that from now on, all your CodeFluent Entities projects will be fully documented .

This article is only a little overview of CodeFluent Entities templating mechanisms and the CodeFluent API features. You will find the sample code and the generated documentation inside the following zip code. You can find the corresponding materials here.

Antoine Diekmann – SoftFluent

Categories: Documentation, Templates
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 51 other followers