Documenting Source Code
The Doxygen export process converts all of the inline comments seen in the Cinder source code into documentation. For instance, you might notice block comments above each method that resemble this if you open a header file.
[from Surface.h]
/** \brief creates a Surface concurrently from photos located at a route. Returning the loaded Surface in a surface.
Use this technique if you want to create a Surface from an image that isn't in the WinRT Windows Store App folder.
**/
or simple remarks like this
//! Provides the Surface's width in pixels.
A portion of doxygen markdown is supported if you decide to contribute to the inline source documentation, including but not restricted to:
- Adding inline links: [The link text](http://example.net/)
- Code Block Indentation
- \a <word> in italics
- \p <word> for monospace font
- \see { references }
Observe that not. It is strongly advised that you instead contribute to external documentation, as explained below if you want to accomplish anything complicated.
External Documentation
There is a different method for writing extra documentation and guides for the documents. It may be found in the htmlsrc/ directory and is all written in HTML. For further information, see the Docs File Structure. You will primarily be interested in the _docs and guidelines directories unless you are contributing to the markup of the entire documentation site. While the guides directory has all of the content for the Cinder guidelines, the _docs directory contains markup and other files for class descriptions. Let's examine the ci> tag first before getting into the mechanics of authoring each form of an external document.
The <ci> tag
We've developed a new ci> tag to help bridge the gap between the Cinder source reference sites and the additional HTML markup. This element is utilized to both offer a mechanism for reference pages to connect back to our guides and to specify any HTML material found in the supplemental documentation that needs to be linked to the source reference.
Use-Cases for the <ci> tag are:
- The creation of a link to a source documentation page
- Providing a description for a particular class, interface, or struct
- To connect a manual to a certain class reference page
Writing Guides
The steps below should be followed while writing a tutorial for the Cinder documentation:
- Within the docs/htmlsrc/guides directory, make a new directory. The directory's name must be succinct and informative (ex: audio, mac-setup, cinder-blocks, etc.)
- Copy the contents of the HTML file located at _start-here/start-here.html into a new index.html file that you create in your new directory. All of the CSS and JavaScript connections utilized in the resulting HTML directory are included in the file. Although not necessary, this will provide you with a precise glimpse of how your guide will seem after integration.
- Create your manual with HTML. If you'd like, you can use your own JavaScript and CSS.
- Make a configuration file if your site has many pages.
- Incorporate searchable meta keywords into the documents..
- Any classes that may be relevant should have any ci> see also tags added (That is also part of configuring multiple pages).
- Make a GitHub pull request.
The config file
If your guide has numerous pages, you can optionally include a config.json file for your convenience. Instead of having to specify meta keywords for every page in your guide, you can use this file to specify the pages that come into the guide for sub-navigation.
This is an example taken from the Path2d guide:
{
"data":{
// keywords for finding this guide via search
"metadata":
{
"keywords": ["path2d", "shape2d", "bezier", "curves", "path", "lines"]
},
// subnavigation for every page of the guide
"subnav":[
{
"label": "Part 1", // label for the subnav link
"link": "part1.html" // link for the subnav link
},
{
"label": "Part 2",
"link": "part2.html"
},
{
"label": "Part 3",
"link": "part3.html"
}
],
"seealso":
{
"label": "Path2d Guide", // label for the see also link(s)
"dox": ["ci::Path2d", "ci::Shape2d"] // classes to be linked from
}
}
}
Frequently Asked Questions
What is Cinder?
The capabilities of the C++ language for sophisticated visualization were improved with the creation of an open-source package called Cinder. In many aspects, it can be thought of as a C++-based replacement for technologies such as the Java-based Processing library, Microsoft Silverlight, or Adobe Flash.
What is CinderBlocks?
A CinderBlock is a pre-built set of code and libraries that executes a feature or provides a library in Cinder. This comprises bridges to packages like OpenCV and FMOD as well as standalone implementations of features like TUIO support. Built-in CinderBlocks that come by default with Cinder are QuickTime and the LocationManager. The source code, header files, libraries, and other components that a CinderBlock requires may be included.
What is TinderBox?
Although using TinderBox, Cinder's application-building tool is the simplest way to use CinderBlocks. It is not essential to do so; a skilled C++ user can easily add a CinderBlock to a project.
What is the source pattern element used for?
With the syntax src/*.cpp, all files matching the pattern, including wildcards (*), are included as references.
What language is Cinder?
Cinder is in C++ language.
Conclusion
This article discussed all about documenting Cinder. Further we also discussed Docs Generation Process, Docs File Structure and External documentation for Cinder. To enhance your knowledge on Cinder, check these blogs-
Refer to our guided paths on Coding Ninjas Studio to learn more about DSA, Competitive Programming, JavaScript, System Design, etc. Enroll in our courses and refer to the mock test and problems available; look at the Top 150 Interview Puzzles, interview experiences, and interview bundle for placement preparations. Read our blogs on aptitude, competitive programming, interview questions, IT certifications, and data structures and algorithms for the best practice.
27+ registered 
