Code Examples
Add code examples where possible to show users how to work with Couchbase products.
When adding a code example:
- Do
-
-
Make it relevant and applicable to your explanation.
-
Make sure it is a working code sample that the user could use in their own projects.
-
Put the code example in its own separate file.
-
Use the correct format for Code Placeholders.
-
- Don’t
-
-
Include cultural references.
-
Write the code sample directly inside the .adoc file.
-
Introducing Examples
Use the following guidelines for adding an example into your documentation:
-
Don’t use directional language to describe where in the text your example is, like "above" or "below." Use "preceding," "previous," or "following."
-
Similar to links, use "see."
-
Use a colon at the end of the phrase you use to introduce your example.
Acceptable | Not Acceptable |
---|---|
See the following example: |
See the example below. |
For an example of how to use a The following example shows how to use a |
The example below shows how to use a |
Adding a Code Example
Antora supports two different methods of inserting smaller blocks of code into a page:
-
Add tags inside code comments to mark the code to include.
-
Choose specific line numbers to include.
Tags
To start a code sample, in the source code file, add tag::<TAG_NAME>[]
in a code comment before the lines of code you want to include.
To end a code sample, in the source code file, add end::<TAG_NAME>[]
in a code comment following the lines of code you want to include.
For example, the following code has two tags, using
and connect
:
c#using System;
// #tag::using[]
using System.Threading.Tasks;
using Couchbase;
// #end::using[]
namespace examples
{
class StartUsing
{
static async Task Main(string[] args)
{
// #tag::connect[]
var cluster = await Cluster.ConnectAsync("couchbase://localhost", "username", "password");
// #end::connect[]
...
}
}
}
Line Numbers
To include a specific set of lines of code in your code, use the lines
attribute inside your include directive.
For example, the following code would include lines 1-3 of the code file select-true-alias-get-business-days.n1ql
:
include::example$javascript-udfs/select-true-alias-get-business-days.n1ql[lines=1..3]
For more information about how to include specific lines of content, see Include Content by Line Ranges in the Asciidoctor Documentation.
Explaining Code Examples
Avoid the built-in code callouts in Antora, where possible.
Use small code examples with the explanation in regular text around the example. Add one-line code comments directly to the code where appropriate to explain the assumptions made in a code example.
Let the user know they should remove the comments to use the code in a production environment.
When you need to explain a larger code example:
-
Show the full example and provide a brief explanation.
-
Create a smaller code example out of the larger block of code.
-
Provide a more detailed explanation for the smaller code example.
-
Repeat Steps 2 and 3 until you’ve explained the code.