Descriptive reference documentation built in into RSDL.

[garethj-msft]

In CSDL, the description annotations quickly bloat the file beyond readability if you put them inline. But if you put them in as a big annotation block at the end then it's hard to see if you have missed any and you end up needing tooling to lint missing descriptions.

Description seems so core to an API that it shouldn't be an annotation in RSDL rather a built-in.

So how to proceed. Do we need the one true way or options?

The CSDL annotations also too hard to work out how to target for some elements such as action and function parameters. Let's not repeat that.

[ralfhandl]

We could use XxxDoc-style comments:

/** Employees are the most important resource of a company */
type employee
{
    /** unique identifier of an employee, assigned on entering the company */
    key id: Integer 

    /** the full name of the employee */
    name : name

    /** job title */
    title: String

    action fire(date: Date?) 
    
    /** promote this employee */
    function promote(
      /** how many levels to promote */
      levels: Integer
    ) : /** the actual levels the employee was promoted */ Integer
}

Alternatively we could go for double hashes ## ... because we already decided to go for single hashes for normal comments:

## Employees are the most important resource of a company
type employee
{
    ## unique identifier of an employee, assigned on entering the company
    key id: Integer 

    ## the full name of the employee
    name : name

    ## job title
    title: String

    action fire(date: Date?) 
    
    ## promote this employee
    function promote(
      ## how many levels to promote
      levels: Integer
    ) 
    : ## the actual levels the employee was promoted
    Integer
}

When translated into CSDL, these doc comments would go into @Core.Description.

[GEricson]

We should keep comments separate from element descriptions.

• @description: Employees are the most important resource of a company or
• @descr: Employees are the most important resource of a company or
• @d: Employees are the most important resource of a company

A case to be made to distinguish between normative descriptions and informative descriptions. For normative, I'd prefer using something like:

• @constraint: {language="en", "This value shall be a shade of blue."} or
• @constraint: (language:"ocl", body="self. ...."}

[ralfhandl]

We should keep comments separate from element descriptions

We are using special syntax for an ## element description which is syntactically different from a # comment, and both are different from an @annotation.

The two pieces of meta-information mainly targeted at human readers look similar, and both look distinctly different from meta-information mainly targeted at machines.

[garethj-msft]

We should keep comments separate from element descriptions

We are using special syntax for an ## element description which is syntactically different from a # comment, and both are different from an @annotation.

The two pieces of meta-information mainly targeted at human readers look similar, and both look distinctly different from meta-information mainly targeted at machines.

I very much like the readability and minimalism of the '##' . Minor concern that when fast scanning it might be easy to not see the difference between one and two, but not that much of a worry.

[ralfhandl]

it might be easy to not see the difference between one and two

We can assign different scope names and syntax colors:

• ## ... becomes comment.block.documentation
• # ... becomes plain comment or comment.line

[chrisspre]

Todo:

• [x] fix javascript parser
• [ ] fix dotnet parser
• [x] fix ABNF

[mikepizzo]

New syntax implemented for javascript in #259. ABNF added in #271. Need to implement in C# parser.