Skip to content

Documentation

Guide

The developer's guide is a collection of the most important information and good practices in the project.It is created based on the Markdown syntax and the VitePress library. The guide is divided into two sections:

  • development - Here you can find all information related to tools, processes, answers to potential questions;
  • components - This is a list of all components with a detailed description of the components of each component.

The documentation configuration is found in the docs/.vitepress folder. There are three important files there:

  • config.ts - contains navigation of all documentation elements and elements important for Vitepress configuration;
  • theme/index.ts - installs documentation components (UI) and components of the proper library;
  • theme/custom.css - contains overwriting the default settings for the documentation.

README

The simplest and at the same time one of the best ways to document work, describing issues related to the code and business context is to create files called README.md, and thus using the Markdown syntax.The repository has one main README.md file describing the repository and providing the most important information about it.

However, there are no contraindications to create such a file in every folder that contains a code requiring a LYB description, whose reading in the future will require recalling business assumptions. This is recommended especially if the code lacks comments or are incomplete, they do not provide sufficient knowledge.

README.md documents can contain use cases, detailed descriptions, code, data tables, in other words anything that can later be read and formatted with Markdown.

Vitepress

This is software that generates documentation in projects based on Markdown documents. You can read more about generation on the official Vitepress website.

In the Riupress UI library, Vitepress is the basic documentation creation tool. Thanks to the fact that markdown in Vitepress interprets all Vue component tags correctly, it is possible to display them in the documentation. This allows you to present components as in Figma.

TIP

VitePress is a basic tool for documenting Riupress projects.

JSDOC comments

JSDoc is an API documentation generator for JavaScript. You add documentation comments directly to the source code, right next to the code itself. The purpose of JSDoc is to document an application's API or JavaScript/TypeScript library. It is assumed that the developer will want to document things such as modules, namespaces, classes, methods, method parameters, and so on.

Comments should be placed immediately before code documentation. Each comment must begin with the sequence /** to be recognized by the JSDoc parser. Comments starting with /*, /*** or more than 3 stars will be ignored.

Examples:

ts
/** This is a description of the foo function. */
function foo() {}
ts
/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {}
ts
/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {}

Creating comments is supported by a plugin Document This for VSCode.

TIP

Commenting code is one of the best practices regardless of the language in which we deliver software. Thanks to comments, your editor will better advise you what the function, class, etc. you are highlighting is for. - no need to open file with class.

Figma

Figma is the most important source of knowledge about what the components should look like, so it is also the documentation of the project. You can read more about Figma here.