{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"6"},"outline":{"value":"false"},"style":{"value":"decimal"},"type":{"value":"list"},"printable":{"value":"true"}},"macroMetadata":{"macroId":{"value":"dfb45081-d4ec-4c8b-ad67-8f7c91cf1663"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"aa6492ae-45ca-4357-8758-3dd2580dc90d"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"What Are Code Interfaces?","type":"text"}]},{"type":"paragraph","content":[{"text":"“Code interfaces” is a term used here to refer to any kind of code that another programmer might need to understand and “interface with” when working on code.","type":"text"}]},{"type":"paragraph","content":[{"text":"It doesn’t just mean “public interfaces” that would exist in a released library or API - when maintaining code, all levels of “interfaces” (even internal/private ones) are important to understand. Such interfaces can include namespaces/packages, files/modules, data types, functions, variables, or potentially other things.","type":"text"}]},{"type":"paragraph","content":[{"text":"Any “symbol” in code that another programmer might have to use (or maintain) is important enough to understand and thus likely warrants being commented. Making sure the interfaces to that code are well-documented is important for team productivity and success.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are some places where some of this documentation may seem overly obvious/redundant. We’ll also cover some techniques that can help minimize this and aid in ","type":"text"},{"text":"comment maintainability","type":"text","marks":[{"type":"link","attrs":{"href":"https://edensoftlabs.atlassian.net/wiki/spaces/edensoftlabs/pages/91881645"}}]},{"text":".","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1820,"alt":"Insights from every commit ad.png","id":"ca24453d-72e1-47e6-9445-a6be3da5c3df","collection":"contentId-91783481","type":"file","height":376},"marks":[{"type":"link","attrs":{"href":"https://www.pulsepoint-ai.com/developers"}}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Documentation Styles & Generators","type":"text"}]},{"type":"paragraph","content":[{"text":"Documenting code interfaces is often covered by many coding standards, which may mandate specific styles.","type":"text"}]},{"type":"paragraph","content":[{"text":"However, many styles are supported by various common ","type":"text"},{"text":"documentation generators","type":"text","marks":[{"type":"em"}]},{"text":". Documentation generators tend to provide the following benefits:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A standardized format for many kinds of documentation:","type":"text","marks":[{"type":"strong"}]},{"text":" A consistent format saves time by reducing the time needed for people to decide on a documentation style or interpret someone else’s format. The consistency helps teams of programmers focus more on the more valuable ","type":"text"},{"text":"documentation content","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ability to generate web-browsable documentation: ","type":"text","marks":[{"type":"strong"}]},{"text":"Documentation generators can extract comments from the code itself and generate HTML documentation that can be navigated in a web browser. This can be particularly valuable for code that serves as a public API/library.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Automated checks for incorrect documentation: ","type":"text","marks":[{"type":"strong"}]},{"text":"Due to the more free-form nature of documentation, documentation generators can’t warn about everything that may be wrong in documentation. But many documentation generators warn for things like missing parameter or return value documentation, providing some automatic safety net in keeping documentation up-to-date.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Some common documentation styles/generators include:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Doxygen","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.doxygen.nl/"}}]},{"text":" (multiple languages)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"XML documentation comments","type":"text","marks":[{"type":"link","attrs":{"href":"https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/"}}]},{"text":" (C#)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Javadoc","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.oracle.com/java/technologies/javase/javadoc-tool.html"}}]},{"text":" (Java)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Python docstrings","type":"text","marks":[{"type":"link","attrs":{"href":"https://peps.python.org/pep-0257/"}}]},{"text":" (Python)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Napoleon-style docstrings","type":"text","marks":[{"type":"link","attrs":{"href":"https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html"}}]},{"text":" (Python)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Sphinx","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.sphinx-doc.org/"}}]},{"text":" (multiple languages)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"JSDoc","type":"text","marks":[{"type":"link","attrs":{"href":"https://jsdoc.app/"}}]},{"text":" (JavaScript)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"TSDoc","type":"text","marks":[{"type":"link","attrs":{"href":"https://tsdoc.org/"}}]},{"text":"/","type":"text"},{"text":"TypeDoc","type":"text","marks":[{"type":"link","attrs":{"href":"https://typedoc.org/"}}]},{"text":" (TypeScript)","type":"text"}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1820,"alt":"Find the experts Ad.png","id":"14ecc531-beaf-4e7c-be8b-b406a87d206d","collection":"contentId-91783481","type":"file","height":375},"marks":[{"type":"link","attrs":{"href":"https://www.pulsepoint-ai.com/developers"}}]}]},{"type":"paragraph","content":[{"text":"This training will leverage some of these common formats in examples. But the specifics of a style are less important than the content of the documentation. So if you have a different style, the guidance outlined here should be transferrable to your style.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Python documentation styles in particular can widely vary, and getting a particular style to work right can depend on specific configuration. With such wide variety, it’s hard to cover every single Python documentation style in every example. This training will aim to cover 3 common yet fairly different styles - Doxygen, Sphinx reST docstrings, and Google-style docstrings - at least in examples for function documentation.","type":"text"}]},{"type":"paragraph","content":[{"text":"For other examples, documentation may be restricted to one style (often Doxygen-style, since that tends to be most concise for code examples). However, outside of functions, there are fewer specific “tags.” so it’s mainly the core content of the comments that comes into play. The content of the comments should be easily transferrable to other styles, so check coding standards your organization has adopted.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Essential Tags for Common Documentation Generators","type":"text"}]},{"type":"paragraph","content":[{"text":"Most documentation generators leverage specific “tags” that can be inserted into comments to identify the specific kind of entity in code being documented - parameters, return values, etc.. This structured format is how documentation generators can understand and parse comments correctly.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following are some essential tags across several common documentation generators:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"edb62b6e-375a-40a0-b06c-f344e08a8c93"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Doxygen","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"a2bfccce-6340-438d-bbb1-ed66113e3f2c"}},{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"C# XML","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Javadoc","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Sphinx","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"JSDoc","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Overall description","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"\\brief","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"\\detailed","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"*Though typically no-longer needed.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"

","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"@description","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"@summary","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"*Though typically not needed.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Parameter","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"\\param","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"@param","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":":param","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"@param","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Return Value","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"\\return","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"@return","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":":return","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"@returns","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Exception","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"\\throws","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"\\exception","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"@throws","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"@exception","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":":raises","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"@throws","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1820,"alt":"Say goodbye to blindsided code updates ad.png","id":"9f70d3a8-de2d-4ae5-92d0-83b07e293d2e","collection":"contentId-91783481","type":"file","height":376},"marks":[{"type":"link","attrs":{"href":"https://www.pulsepoint-ai.com/developers"}}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Putting it All Together - An Example","type":"text"}]},{"type":"paragraph","content":[{"text":"The following example demonstrates how many of the techniques described in this section can come together using some documentation-generator styles mentioned above:","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"navitabs-tab-wizard","parameters":{"macroParams":{"__bodyContent":{"value":"{\"type\":\"custom\",\"custom\":{\"tabs\":[{\"id\":\"61311c8c-d4fd-4e66-857e-4cba9e99ddf6\",\"value\":\"C++\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"c++\"},\"content\":[{\"type\":\"text\",\"text\":\"/// Holds code related to computer graphics.\\n/// Performance is critically important for this code,\\n/// so code in this namespace should be heavily optimized.\\nnamespace GRAPHICS\\n{\\n /// Supported color formats.\\n /// Only color formats currently supported are listed here.\\n /// If new formats need to be supported, they can be added.\\n enum class ColorFormat\\n {\\n /// Color channels are ordered from red, green, blue, and then alpha.\\n /// This is the most common color format, so it is the default value for this enum.\\n RGBA = 0,\\n /// Color channels are ordered from alpha, red, green, and then blue.\\n ARGB\\n };\\n \\n /// A color following the RGBA (red, green, blue, alpha) color model\\n /// (https://en.wikipedia.org/wiki/RGBA_color_model).\\n /// Color channels are represented as floating-point components in the range of [0,1]\\n /// for easy interoperability with 3D computer graphics code but can be converted to\\n /// other formats like 8-bit integers in the range of [0,255].\\n class Color\\n {\\n public:\\n // PUBLIC METHODS.\\n template \\n PackedIntegerType Pack(const ColorFormat color_format) const;\\n \\n // PUBLIC MEMBER VARIABLES FOR EASY ACCESS.\\n /// The red channel of the color, between [0,1].\\n /// Initialized to 0 so that a default-constructed color will be black.\\n float Red = 0.0f;\\n /// The green channel of the color, between [0,1].\\n /// Initialized to 0 so that a default-constructed color will be black.\\n float Green = 0.0f;\\n /// The blue channel of the color, between [0,1].\\n /// Initialized to 0 so that a default-constructed color will be black.\\n float Blue = 0.0f;\\n /// The alpha channel of the color, between [0,1].\\n /// Initialized to 1 so that a default-constructed color is\\n /// considered fully-opaque (the intuitive human default for colors),\\n /// rather than having any transparency.\\n /// 0 indicates fully transparent.\\n float Alpha = 1.0f;\\n };\\n \\n /// Packs the color's channels into a single integer value according to\\n /// the specified format.\\n /// \\\\tparam PackedIntegerType - The specific integer type in which to pack \\n /// the color channels.\\n /// Templated to provide flexibility when interoperating with other code.\\n /// \\\\param[in] color_format - The format in which to pack the color.\\n /// \\\\return The color packed into the specified type of integer.\\n template \\n PackedIntegerType Color::Pack(const ColorFormat color_format) const\\n {\\n // ...\\n }\\n}\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"type\":\"your-content\"},{\"id\":\"b5993648-661c-4297-9ab7-601dd290214c\",\"value\":\"C#\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"csharp\"},\"content\":[{\"type\":\"text\",\"text\":\"///

\\n/// Holds code related to computer graphics.\\n/// Performance is critically important for this code,\\n/// so code in this namespace should be heavily optimized.\\n///

\\nnamespace Graphics\\n{\\n ///

\\n /// Supported color formats.\\n /// Only color formats currently supported are listed here.\\n /// If new formats need to be supported, they can be added.\\n ///

\\n public enum ColorFormat\\n {\\n ///

\\n /// Color channels are ordered from red, green, blue, and then alpha.\\n /// This is the most common color format, so it is the default value for this enum.\\n ///

\\n RGBA = 0,\\n ///

\\n /// Color channels are ordered from alpha, red, green, and then blue.\\n ///

\\n ARGB\\n }\\n\\n ///

\\n /// A color following the RGBA (red, green, blue, alpha) color model\\n /// (https://en.wikipedia.org/wiki/RGBA_color_model).\\n /// Color channels are represented as floating-point components in the range of [0,1]\\n /// for easy interoperability with 3D computer graphics code but can be converted to\\n /// other formats like 8-bit integers in the range of [0,255].\\n ///

\\n public class Color\\n {\\n #region Public Properties\\n ///

\\n /// The red channel of the color, between [0,1].\\n /// Initialized to 0 so that a default-constructed color will be black.\\n ///

\\n public float Red { get; set; } = 0.0f;\\n ///

\\n /// The green channel of the color, between [0,1].\\n /// Initialized to 0 so that a default-constructed color will be black.\\n ///

\\n public float Green { get; set; } = 0.0f;\\n ///

\\n /// The blue channel of the color, between [0,1].\\n /// Initialized to 0 so that a default-constructed color will be black.\\n ///

\\n public float Blue { get; set; } = 0.0f;\\n ///

\\n /// The alpha channel of the color, between [0,1].\\n /// Initialized to 1 so that a default-constructed color is considered fully opaque.\\n /// 0 indicates fully transparent.\\n ///

\\n public float Alpha { get; set; } = 1.0f;\\n #endregion\\n\\n #region Public Methods\\n ///

\\n /// Packs the color's channels into a single integer value according to\\n /// the specified format.\\n ///

\\n /// The specific integer type in which to pack\\n /// the color channels.\\n /// The format in which to pack the color.\\n /// The color packed into the specified type of integer.\\n public PackedIntegerType Pack(ColorFormat colorFormat)\\n {\\n // ...\\n }\\n #endregion\\n }\\n}\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"type\":\"your-content\"},{\"id\":\"fe9988f8-a3dd-41b0-93a6-f76195d8ce40\",\"value\":\"Java\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"java\"},\"content\":[{\"type\":\"text\",\"text\":\"/**\\n * Holds code related to computer graphics.\\n * Performance is critically important for this code,\\n * so code in this package should be heavily optimized.\\n */\\npackage graphics;\\n\\n/**\\n * Supported color formats.\\n * Only color formats currently supported are listed here.\\n * If new formats need to be supported, they can be added.\\n */\\npublic enum ColorFormat \\n{\\n /**\\n * Color channels are ordered from red, green, blue, and then alpha.\\n * This is the most common color format, so it is the default value for this enum.\\n */\\n RGBA,\\n /**\\n * Color channels are ordered from alpha, red, green, and then blue.\\n */\\n ARGB\\n}\\n\\n/**\\n * A color following the RGBA (red, green, blue, alpha) color model\\n * (https://en.wikipedia.org/wiki/RGBA_color_model).\\n * Color channels are represented as floating-point components in the range of [0,1]\\n * for easy interoperability with 3D computer graphics code but can be converted to\\n * other formats like 8-bit integers in the range of [0,255].\\n */\\npublic class Color \\n{\\n /**\\n * The red channel of the color, between [0,1].\\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n public float red = 0.0f;\\n /**\\n * The green channel of the color, between [0,1].\\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n public float green = 0.0f;\\n /**\\n * The blue channel of the color, between [0,1].\\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n public float blue = 0.0f;\\n /**\\n * The alpha channel of the color, between [0,1].\\n * Initialized to 1 so that a default-constructed color is considered fully opaque\\n * (the intuitive human default for colors), rather than having any transparency.\\n * 0 indicates fully transparent.\\n */\\n public float alpha = 1.0f;\\n\\n /**\\n * Packs the color's channels into a single integer value according to\\n * the specified format.\\n * @param - The specific integer type in which to pack\\n * the color channels.\\n * @param colorFormat The format in which to pack the color.\\n * @return The color packed into the specified type of integer.\\n */\\n public PackedIntegerType pack(ColorFormat colorFormat) \\n {\\n // ...\\n }\\n}\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"type\":\"your-content\"},{\"id\":\"6db21f5d-e76d-4808-8d9f-7e38ef5aec55\",\"value\":\"Python (Doxygen)\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"python\"},\"content\":[{\"type\":\"text\",\"text\":\"## \\\\package graphics\\n## Holds code related to computer graphics.\\n## Performance is critically important for this code,\\n## so code in this namespace should be heavily optimized.\\n\\nfrom dataclasses import dataclass\\nfrom enum import Enum\\n\\n## Supported color formats.\\n## Only color formats currently supported are listed here.\\n## If new formats need to be supported, they can be added.\\nclass ColorFormat(Enum):\\n ## Color channels are ordered from red, green, blue, and then alpha.\\n RGBA = \\\"RGBA\\\"\\n ## Color channels are ordered from alpha, red, green, and then blue.\\n ARGB = \\\"ARGB\\\"\\n\\n## A color following the RGBA (red, green, blue, alpha) color model\\n## (https://en.wikipedia.org/wiki/RGBA_color_model).\\n## Color channels are represented as floating-point components in the range of [0,1]\\n## for easy interoperability with 3D computer graphics code but can be converted to\\n## other formats like 8-bit integers in the range of [0,255].\\n@dataclass\\nclass Color:\\n ## The red channel of the color, between [0,1].\\n ## Initialized to 0 so that a default-constructed color will be black.\\n red: float = 0.0\\n ## The green channel of the color, between [0,1].\\n ## Initialized to 0 so that a default-constructed color will be black.\\n green: float = 0.0\\n ## The blue channel of the color, between [0,1].\\n ## Initialized to 0 so that a default-constructed color will be black.\\n blue: float = 0.0\\n ## The alpha channel of the color, between [0,1].\\n ## Initialized to 1 so that a default-constructed color is considered fully opaque.\\n ## 0 indicates fully transparent.\\n alpha: float = 1.0\\n\\n ## Packs the color's channels into a single integer value according to the specified format.\\n ##\\n ## \\\\param color_format The format in which to pack the color.\\n ## \\\\return The color packed into an integer.\\n def pack(self, color_format: ColorFormat) -> int:\\n # ...\\n pass\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"type\":\"your-content\"},{\"id\":\"d19eb5d4-5de3-43ca-9609-119f2f6237ba\",\"value\":\"JavaScript\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"javascript\"},\"content\":[{\"type\":\"text\",\"text\":\"/**\\n * Holds code related to computer graphics.\\n * Performance is critically important for this code,\\n * so the code in this namespace should be heavily optimized.\\n */\\nconst Graphics = \\n{\\n /**\\n * Supported color formats.\\n * Only color formats currently supported are listed here.\\n * If new formats need to be supported, they can be added.\\n */\\n ColorFormat:\\n {\\n /**\\n * Color channels are ordered from red, green, blue, and then alpha.\\n */\\n RGBA: \\\"RGBA\\\",\\n /**\\n * Color channels are ordered from alpha, red, green, and then blue.\\n */\\n ARGB: \\\"ARGB\\\"\\n },\\n\\n /**\\n * A color following the RGBA (red, green, blue, alpha) color model\\n * (https://en.wikipedia.org/wiki/RGBA_color_model).\\n * Color channels are represented as floating-point components in the range of [0,1]\\n * for easy interoperability with 3D computer graphics code but can be converted to\\n * other formats like 8-bit integers in the range of [0,255].\\n */\\n Color: class \\n {\\n /** \\n * The red channel of the color, between [0,1]. \\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n red = 0.0;\\n /** \\n * The green channel of the color, between [0,1]. \\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n green = 0.0;\\n /** \\n * The blue channel of the color, between [0,1]. \\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n blue = 0.0;\\n /** \\n * The alpha channel of the color, between [0,1]. \\n * Initialized to 1 so that a default-constructed color is\\n * considered fully-opaque (the intuitive human default for colors),\\n * rather than having any transparency.\\n * 0 indicates fully transparent.\\n */\\n alpha = 1.0;\\n\\n /**\\n * Packs the color's channels into a single integer value according to\\n * the specified format.\\n * @param {number} colorFormat - The format in which to pack the color.\\n * @returns {number} The color packed into an integer.\\n */\\n pack(colorFormat) \\n {\\n // ...\\n }\\n }\\n};\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"type\":\"your-content\"},{\"id\":\"d449b6ec-19da-4485-9fa6-7044220a92b2\",\"value\":\"TypeScript\",\"body\":{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"typescript\"},\"content\":[{\"type\":\"text\",\"text\":\"/**\\n * Holds code related to computer graphics.\\n * Performance is critically important for this code,\\n * so code in this namespace should be heavily optimized.\\n */\\nnamespace Graphics\\n{\\n /**\\n * Supported color formats.\\n * Only color formats currently supported are listed here.\\n * If new formats need to be supported, they can be added.\\n */\\n export enum ColorFormat\\n {\\n /**\\n * Color channels are ordered from red, green, blue, and then alpha.\\n */\\n RGBA: \\\"RGBA\\\",\\n /**\\n * Color channels are ordered from alpha, red, green, and then blue.\\n */\\n ARGB: \\\"ARGB\\\"\\n }\\n\\n /**\\n * A color following the RGBA (red, green, blue, alpha) color model\\n * (https://en.wikipedia.org/wiki/RGBA_color_model).\\n * Color channels are represented as floating-point components in the range of [0,1]\\n * for easy interoperability with 3D computer graphics code but can be converted to\\n * other formats like 8-bit integers in the range of [0,255].\\n */\\n export class Color\\n {\\n /**\\n * The red channel of the color, between [0,1].\\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n public red: number = 0.0;\\n /**\\n * The green channel of the color, between [0,1].\\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n public green: number = 0.0;\\n /**\\n * The blue channel of the color, between [0,1].\\n * Initialized to 0 so that a default-constructed color will be black.\\n */\\n public blue: number = 0.0;\\n /**\\n * The alpha channel of the color, between [0,1].\\n * Initialized to 1 so that a default-constructed color is considered fully opaque.\\n * 0 indicates fully transparent.\\n */\\n public alpha: number = 1.0;\\n\\n /**\\n * Packs the color's channels into a single integer value according to\\n * the specified format.\\n * @param colorFormat - The format in which to pack the color.\\n * @returns The color packed into an integer.\\n */\\n public pack(colorFormat: ColorFormat): number \\n {\\n // ...\\n }\\n }\\n}\"}]},{\"type\":\"paragraph\",\"content\":[]}]},\"type\":\"your-content\"}],\"design\":null,\"minHeight\":0,\"vertical\":false,\"isEmbedded\":false}}"}},"macroMetadata":{"macroId":{"value":"7bbe1221-51aa-4eb9-8ca6-9c2330e9d133"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://us.navitabs-static-assets.aws.bitvoodoo.cloud/static/3.3.0/images/macro-icon.png"}}],"title":"Tab Wizard"}},"localId":"96f83749-ec8a-4af8-aac1-bd423333f37e"}},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1822,"alt":"Tap into your teams collective wisdom ad.png","id":"6988310b-f98b-4d2b-892a-603e065acbb9","collection":"contentId-91783481","type":"file","height":377},"marks":[{"type":"link","attrs":{"href":"https://www.pulsepoint-ai.com/developers"}}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Documenting Different Types of Code Interfaces","type":"text"}]},{"type":"paragraph","content":[{"text":"Different types of code interfaces can have specific considerations. The sections linked to below give tips on documenting different common types of interfaces:","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"children","parameters":{"macroParams":{"all":{"value":"true"},"depth":{"value":"0"},"allChildren":{"value":"true"},"style":{"value":""},"sortAndReverse":{"value":""},"first":{"value":"0"}},"macroMetadata":{"macroId":{"value":"f36b020044d9af8fa089027cd6faff19f40f8a0ffdb510e5fccdfe6c731053f0"},"schemaVersion":{"value":"2"},"title":"Child pages (Children Display)"}},"localId":"4ab02b30-0e26-42b4-b141-33b70d5e52d4"}},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2051,"alt":"Code More Meet Less Ad.png","id":"df55e42c-b1e3-4862-8ea4-dc2eebf69389","collection":"contentId-91783481","type":"file","height":569},"marks":[{"type":"link","attrs":{"href":"https://www.pulsepoint-ai.com/developers"}}]}]}],"version":1}