Documentation/GSoDOC/2022

Objective:
Add examples (code snippets) in API pages (idl files).

The Problem:
The LibreOffice API is extracted from the source code (Doxygen) and is shallow in terms of examples for the occasional script programmer. Furthermore, for the occasional script writer, the complexity of the LibreOffice API is daunting at best. The reason is in great part as consequence of the C++ object oriented programming, which is suited for the professional developer rather than the occasional macro writer, looking to solve a spreadsheet or text document handling.

We envision that with a medium to complete set of code snippets, we will address the need of the macro programmer with a quick way to use the API in the right way and with much less trial and error coding.

The Scope
The scope of the project is the LibreOffice API illustration by examples.


 * Understand the API documentation tools generator (Doxygen)
 * Address a set of API objects, properties, constants, methods and services and supply code fragments showing how to use it. Code snippets must be commented.
 * Work with the LibreOffice script community on the subject
 * Be part of the scripting documentation team, in producing scripting documentation for the end user.

Results expected:
Better illustration of API usage, turning API pages more user-friendly for the occasional macro programmer either in Python or Basic.

Measuring Results

 * An initial set of API entries to be addressed will be defined.
 * The measurement of the progress will done by reading the % of the accomplished tasks with respect of the initial set.
 * All results will be visible in the source code of LibreOffice, immediately

Additional Information
LibreOffice participated in Google Seasons of Doc in 2019 and 2020 and it's mentors are fully qualified to provide guidance for the technical writer. LibreOffice also participates actively in the Google Summer of Code since 2011.

In 2019 we produced a guide for LibreOffice Online available at https://nextcloud.documentfoundation.org/s/gRSwD4E7bSCe4w8.

Our mentoring consisted on the following actions
 * Established a weekly online meeting for project follow-up
 * Provided all infrastructure and access to the relevant information for the technical writer
 * Advise on important topics of the contents.
 * Advise on writing style and docuement formatting for the final product

In 2020 we conducted 2 projects:
 * E-Learning Calc : https://wiki.documentfoundation.org/Documentation/GSoDOC/2020#LibreOffice_E-Learning_Calc
 * Transposition of the LibreOffice Calc Guide (Spreadsheet) into online learning class
 * Improvements in video sketches in the lessons
 * Calc Function Reference: https://wiki.documentfoundation.org/Documentation/GSoDOC/2020#Calc_Functions_Reference_and_User_Guide
 * Created a full set of wiki pages with extended information on the Calc Functions (spreadsheet functions)
 * Added examples and use cases of the functions
 * Fixed documentation issues not detected in the current LibreOffice Help pages
 * Served as reference for improvements of LibreOffice Help pages

The experience in the previous Seasons is key to correctly manage and produce the necessary documentation of the LibreOffice API, a much needed documentation for turn the use of the API more accessible to the end user.

Example of code fragment to create for documentation:
https://gerrit.libreoffice.org/c/core/+/123868

From LibreOffice 7.3 on:

https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1frame_1_1XInfobarProvider.html

Notes:

 * No need for translation
 * files to edit are in offapi/ module
 * build and test is done in odk/ module

Skills:

 * Programming 101,
 * Build LibreOffice
 * Gerrit use