Structure CRMScript Documentation
The documentation team spent a significant amount of time updating the CRMScript API reference documentation, which lead to some in-app editor improvements as well.
Key changes included converted 9756 unstructured markdown files down into just 570 structured YAML files. The biggest problem with documenting APIs with markdown content is the inconsistency between files. Some authors like to format an API document one way, while another author prefers a different structure. This lead to an enormous about of API files, increasing documentation generation build time, as well as outputing lot of inconsistencies through out the CRMScript API pages.
Figure One: Old markdown structure.
As YAML content, the structure is easily parsed and predictable. With this new format we are able to produce concise and consistent CRMScript documentation, just like the rest of our API reference documentation.
Figure Two: New YAML structured content
To learn more and better understand the YAML structure, make sure to read more about it on our YAML format reference on docs.superoffice.com.
Structured CRMScript Intellisense
In addition to these improvements, it also lead to the improvement of better structured and more consistent CRMScript intellisense.
Figure Three: Old inconsistent CRMScript intellisense.
Looking at the old intellisense in Figure Three, it's hard to know how to intepret what's presented on the screen, and it wasn't always consistent. Sometimes the prototype included a return type, sometimes it was written below. Parameter structures as bullet lists and sometimes just inline the method description.
Figure Four: New structured intellisense.
The new structure follows a consistent and predicable layout, and some methods even provide a clickable example that inserts the code example into the editor window for you!
The new intelliensense structure is:
- Prototype: ReturnType MethodName(Parameter List...)
- Summary and Documentation Link
- Parameter Table (if there are parameters)
- Remarks
- Example
One more thing...
With improvements in CRMScript intellisense, we also added a few extra code snippets for commonly used statements. Now you will find example snippets for the following statements:
- for
- foreach
- if
- if-else
- struct
- try
- try-catch
- while
- script-nuggets (%EJSCRIPT_START% <% %> %EJSCRIPT_END%)
Figure Five: Statement snippets.
If you believe the CRMScript docs can be improved, make sure to check out the CRMScript repo on github and create an issue or, even better, fork it and submit a pull request!