diff --git a/docs/src/contributing/function-documentation-guide.md b/docs/src/contributing/function-documentation-guide.md new file mode 100644 index 0000000..6de77a8 --- /dev/null +++ b/docs/src/contributing/function-documentation-guide.md @@ -0,0 +1,384 @@ +--- +layout: doc +outline: deep +lang: en-US +--- + +# Function Documentation Guide + +This guide explains how to document IronCalc functions following our established format and style conventions. + +## File Structure + +Function documentation files should be placed in the appropriate category directory under `src/functions/`. For example: + +- Financial functions: `src/functions/financial/function-name.md` +- Text functions: `src/functions/text/function-name.md` +- Logical functions: `src/functions/logical/function-name.md` + +## Required Frontmatter + +Every function documentation file must start with this frontmatter: + +```yaml +--- +layout: doc +outline: deep +lang: en-US +--- +``` + +## Document Structure + +A complete function documentation should include the following sections in order: + +### 1. Title + +The title should be the function name followed by the word "function": + +```markdown +# FV function +``` + +Use the exact function name as it appears in IronCalc (case-sensitive). + +### 2. Draft Warning (Optional) + +If the function hasn't been implemented, include this warning box: + +```markdown +::: warning +**Note:** This draft page is under construction 🚧 +::: +``` + +If the function has been implemented but not documented, include this warning box: + +::: warning +🚧 This function is implemented but currently lacks detailed documentation. For guidance, you may refer to the equivalent functionality in [Microsoft Excel documentation](https://support.microsoft.com/en-us/office/excel-functions-by-category-5f91f4e9-7b42-46d2-9bd1-63f26a86c0eb). +::: + +### 3. Overview + +Provide a brief, clear description of what the function does. If the function name is an acronym, expand it using underlined text: + +```markdown +## Overview + +FV (Future Value) is a function of the Financial category that can be used to predict the future value of an investment or asset based on its present value. +``` + +Include: + +- Category (Financial, Text, Logical, etc.) +- Primary purpose +- Key use cases (if helpful) + +### 4. Usage + +This section contains multiple subsections: + +#### 4.1 Syntax + +Format the function syntax with color-coded argument types. Use the following color scheme: + +- **Numbers**: `#2F80ED` (blue) +- **Booleans**: `#27AE60` (green) +- **Text/Strings**: `#2F80ED` (orange) +- **Arrays/Ranges**: `#EB5757` (red) + +**Format:** + +```markdown +### Syntax + +**FUNCTION_NAME(arg1, arg2=default, ...) => return_value** +``` + +**Example:** + +```markdown +### Syntax + +**FV(rate, nper, pmt, pv=0, type=FALSE) => fv** +``` + +**Guidelines:** + +- Use `title` attribute to specify the data type +- Use `style="color:#HEXCODE"` for syntax highlighting +- Include default values for optional arguments using `=default` +- Show the return type after `=>` +- Make the entire syntax **bold** + +#### 4.2 Argument Descriptions + +List each argument with: + +- Argument name in _italics_ +- Data type link (e.g., `[number](/features/value-types#numbers)`) +- Required or optional indicator +- Description + +**Format:** + +```markdown +### Argument descriptions + +- _argname_ ([datatype](/features/value-types#datatype), [required|optional](/features/optional-arguments.md)). Description of the argument. +``` + +**Example:** + +```markdown +### Argument descriptions + +- _rate_ ([number](/features/value-types#numbers), required). The fixed percentage interest rate or yield per period. +- _pv_ ([number](/features/value-types#numbers), [optional](/features/optional-arguments.md)). "pv" is the present value or starting amount of the asset (default 0). +- _type_ ([Boolean](/features/value-types#booleans), [optional](/features/optional-arguments.md)). A logical value indicating whether the payment due dates are at the end (FALSE or 0) of the compounding periods or at the beginning (TRUE or any non-zero value). The default is FALSE when omitted. +``` + +**Guidelines:** + +- Use bullet points (`*`) +- Italicize argument names with `*argname*` +- Link to value types documentation +- Link to optional arguments page when applicable +- Expand acronyms in descriptions using `` tags if helpful +- Mention default values for optional arguments + +#### 4.3 Additional Guidance + +Provide tips, best practices, and important notes about using the function: + +```markdown +### Additional guidance + +- Make sure that the _rate_ argument specifies the interest rate or yield applicable to the compounding period. +- The _pmt_ and _pv_ arguments should be expressed in the same currency unit. +- To ensure a worthwhile result, one of the _pmt_ and _pv_ arguments should be non-zero. +``` + +#### 4.4 Returned Value + +Describe what the function returns: + +```markdown +### Returned value + +FV returns a [number](/features/value-types#numbers) representing the future value expressed in the same [currency unit](/features/units) that was used for the _pmt_ and _pv_ arguments. +``` + +Include: + +- Return type (with link to value types if applicable) +- Units or format if relevant +- Any important characteristics + +#### 4.5 Error Conditions + +List all error scenarios the function may encounter: + +```markdown +### Error conditions + +- In common with many other IronCalc functions, FV propagates errors that are found in any of its arguments. +- If too few or too many arguments are supplied, FV returns the [`#ERROR!`](/features/error-types.md#error) error. +- If the value of any of the _rate_, _nper_, _pmt_ or _pv_ arguments is not (or cannot be converted to) a [number](/features/value-types#numbers), then FV returns the [`#VALUE!`](/features/error-types.md#value) error. +- If the value of the _type_ argument is not (or cannot be converted to) a [Boolean](/features/value-types#booleans), then FV again returns the [`#VALUE!`](/features/error-types.md#value) error. +- For some combinations of valid argument values, FV may return a [`#NUM!`](/features/error-types.md#num) error or a [`#DIV/0!`](/features/error-types.md#div-0) error. +``` + +**Guidelines:** + +- Use bullet points +- Link error types using backticks and the error types page: `` [`#ERROR!`](/features/error-types.md#error) `` +- Reference argument names in italics when discussing specific arguments +- Include the include directive at the end if using the error details snippet: + +```markdown + +``` + +### 5. Details (Optional but Recommended) + +For functions with mathematical formulas or complex behavior, include a Details section: + +```markdown +## Details + +- If $\text{type} \neq 0$, $\text{fv}$ is given by the equation: + $$ \text{fv} = -\text{pv} \times (1 + \text{rate})^\text{nper} - \dfrac{\text{pmt}\times\big({(1+\text{rate})^\text{nper}-1}\big) \times(1+\text{rate})}{\text{rate}}$$ + +- If $\text{type} = 0$, $\text{fv}$ is given by the equation: + $$ \text{fv} = -\text{pv} \times (1 + \text{rate})^{\text{nper}} - \dfrac{\text{pmt}\times\big({(1+\text{rate})^\text{nper}-1}\big)}{\text{rate}}$$ +``` + +**Guidelines:** + +- Use LaTeX math notation with `$` for inline and `$$` for block equations +- Use `\text{}` for variable names in equations +- Explain special cases or edge conditions + +### 6. Examples + +Link to interactive examples in IronCalc: + +```markdown +## Examples + +[See some examples in IronCalc](https://app.ironcalc.com/?example=functionname). +``` + +Replace `functionname` with the actual function name (lowercase). + +### 7. Links + +Provide external references and related functions: + +```markdown +## Links + +- For more information about the concept of "future value" in finance, visit Wikipedia's [Future value](https://en.wikipedia.org/wiki/Future_value) page. +- See also IronCalc's [NPER](/functions/financial/nper), [PMT](/functions/financial/pmt), [PV](/functions/financial/pv) and [RATE](/functions/financial/rate) functions. +- Visit Microsoft Excel's [FV function](https://support.microsoft.com/en-gb/office/fv-function-2eef9f44-a084-4c61-bdd8-4fe4bb1b71b3) page. +- Both [Google Sheets](https://support.google.com/docs/answer/3093224) and [LibreOffice Calc](https://wiki.documentfoundation.org/Documentation/Calc_Functions/FV) provide versions of the FV function. +``` + +**Guidelines:** + +- Include Wikipedia links for concepts when available +- Link to related IronCalc functions in the same category +- Include links to equivalent functions in Excel, Google Sheets, and LibreOffice Calc +- Use bullet points + +## Syntax Coloring Reference + +### Color Codes + +| Data Type | Hex Color | Usage | +| ----------- | --------- | --------------------------------------- | +| Number | `#2F80ED` | All numeric arguments and return values | +| Boolean | `#27AE60` | TRUE/FALSE arguments | +| Text/String | `#F2994A` | Text arguments | +| Array/Range | `#EB5757` | Array or range arguments | + +### Syntax Highlighting Template + +```html +argument_name +``` + +**Examples:** + +- Number: `rate` +- Boolean: `type` +- Text: `text` + +## Formatting Conventions + +### Text Formatting + +- **Function names**: Use exact case as in IronCalc +- **Argument names**: Use _italics_ when referencing in prose +- **Acronyms**: Expand using `` tags: `Future Value` +- **Code/values**: Use backticks for error codes: `` `#ERROR!` `` +- **Links**: Use descriptive link text, not raw URLs + +### Section Headers + +- Use `##` for main sections (Overview, Usage, Details, Examples, Links) +- Use `###` for subsections (Syntax, Argument descriptions, etc.) + +### Lists + +- Use bullet points (`*`) for argument descriptions and error conditions +- Use numbered lists only when order matters + +## Checklist + +Before submitting a function documentation, ensure: + +- [ ] Frontmatter is correct +- [ ] Title follows the format "FUNCTION_NAME function" +- [ ] Overview clearly explains the function's purpose +- [ ] Syntax is color-coded correctly +- [ ] All arguments are documented with correct types +- [ ] Required vs optional arguments are clearly marked +- [ ] Return value is described +- [ ] Error conditions are comprehensive +- [ ] Examples link is included +- [ ] Links section includes relevant references +- [ ] Mathematical formulas (if any) use proper LaTeX syntax +- [ ] All internal links use relative paths +- [ ] Spelling and grammar are correct + +## Example Template + +```markdown +--- +layout: doc +outline: deep +lang: en-US +--- + +# FUNCTION_NAME function + +::: warning +**Note:** This draft page is under construction 🚧 +::: + +## Overview + +FUNCTION_NAME (Acronym Explanation) is a function of the [Category] category that can be used to [primary purpose]. + +[Additional context about when to use this function or related functions.] + +## Usage + +### Syntax + +**FUNCTION_NAME(arg1, arg2=default, arg3=FALSE) => return_value** + +### Argument descriptions + +- _arg1_ ([type](/features/value-types#type), required). Description. +- _arg2_ ([type](/features/value-types#type), [optional](/features/optional-arguments.md)). Description (default value). +- _arg3_ ([Boolean](/features/value-types#booleans), [optional](/features/optional-arguments.md)). Description (default FALSE). + +### Additional guidance + +- Tip or best practice. +- Another important note. + +### Returned value + +FUNCTION_NAME returns a [type](/features/value-types#type) representing [description]. + +### Error conditions + +- General error propagation note. +- Specific error condition with [`#ERROR!`](/features/error-types.md#error) link. +- Another error condition. + + + +## Details + +[Mathematical formulas or detailed explanations if needed] + +## Examples + +[See some examples in IronCalc](https://app.ironcalc.com/?example=functionname). + +## Links + +- Wikipedia link if applicable. +- Related IronCalc functions. +- Microsoft Excel documentation. +- Google Sheets and LibreOffice Calc links. +``` + +## Questions? + +If you have questions about documenting functions, reach out on our [Discord Channel](https://discord.com/invite/zZYWfh3RHJ) or check existing function documentation for examples. diff --git a/docs/src/contributing/how-to-contribute.md b/docs/src/contributing/how-to-contribute.md index c7223de..cfc193b 100644 --- a/docs/src/contributing/how-to-contribute.md +++ b/docs/src/contributing/how-to-contribute.md @@ -6,4 +6,10 @@ lang: en-US # How to Contribute -If you want to give us a hand, take a look at our [GitHub repository](https://github.com/ironcalc/IronCalc?tab=readme-ov-file#collaborators-needed-call-to-action), join our [Discord Channel](https://discord.com/invite/zZYWfh3RHJ) or send us an email to [hello@ironcalc.com](mailto:hello@ironcalc.com). +If you want to give us a hand, take a look at our [GitHub repository](https://github.com/ironcalc/IronCalc?tab=readme-ov-file#collaborators-needed-call-to-action) – we've marked some issues there with the tag 'good first issue' that could serve you as a starting point. + +If you also want to discuss topics, share your thoughts or just say 'hi', you can join our [Discord Channel](https://discord.com/invite/zZYWfh3RHJ) or send us an email to [hello@ironcalc.com](mailto:hello@ironcalc.com). + +## Documentation + +If you're interested in contributing to our documentation, especially function documentation, please see our [Function Documentation Guide](/contributing/function-documentation-guide).