Create a spec document template

[milancurcic]

Currently we don't have a Markdown template for spec documents. We should have one. Benefits include:

• Makes it easier for contributors to write spec docs.
• Ensures consistency if followed.

This could be in a file SPEC_TEMPLATE.md or similar, placed in the root directory, and linked to from WORKFLOW.md and CONTRIBUTING.md.

Inspired by @JHenneberg in #503.

[JHenneberg]

Short summary of the more or less status quo. More or less because it is not consistently used over all documents:

• General structure of the spec file
  • For now mostly like this:

---
title: <MODULE_NAME>
---

# The `<MODULE_NAME>` module

[TOC]

## Introduction

## <OPTIONAL_SECTIONS>

## Procedures and methods provided

### `<PROCEDURE_NAME>` - <SHORT_DESCRIPTION>

• How should procedures be documented:
  • For now mostly according to the Fortran Standard ISO 1539-1 2018 was followed and extended by the subsection Status and Syntax but missing the section Result Characteristics:

### `<PROCEDURE_NAME>` - <SHORT_DESCRIPTION>

#### Status

[<STABLE>, <EXPERIMENTAL>]

#### Description

#### Syntax

#### Class

[<IMPURE>, <PURE>, <ELEMENTAL>,]

#### Arguments

#### Result Value

#### Example

[milancurcic]

Should Class be:

#### Class

[<IMPURE>, <PURE>, <ELEMENTAL>,] [<FUNCTION> <SUBROUTINE>]

?

[JHenneberg]

@milancurcic I think that would be usefull, even though there is the section #### Syntax it would be redundant.

The Syntax section is not needed in the Fortran Std 2018 files because the complete function/procedure is written in the headline.

Fortran Std or GCC Style:

---

ICHAR(C, [, KIND])

Description

Returns the code for the character in the first character position of C in the system’s native character set.

Class

Elemental function.

Arguments

• C : shall be of type character and of length one. Its value shall be that of a character capable of representation in the processor.
• KIND (optional): shall be a scalar integer constant expression.

Result Characteristics

Integer. If KIND is present, the kind type parameter is that specified by the value of KIND; otherwise, the kind type parameter is that of default integer type.

Result Value

The result is the position of C in the processor collating sequence associated with the kind type ...

Example

ICHAR (’X’) has the value 88 on a processor using the ASCII collating sequence for default characters.

---

vs. fortran_stdlib or GCC ICHAR:

---

ICHAR - Code value for character

Status

Stable

Syntax

RESULT = ICHAR(C [, KIND])

Description

Returns the code for the character in the first character position of C in the system’s native character set.

Class

Elemental

Arguments

• C : shall be of type character and of length one. Its value shall be that of a character capable of representation in the processor.
• KIND (optional): shall be a scalar integer constant expression.

Result Value

Integer. If KIND is present, the kind type parameter is that specified by the value of KIND; otherwise, the kind type parameter is that of default integer type.

The result is the position of C in the processor collating sequence associated with the kind type ...

Example

program read_val
  integer value
  character(len=10) string, string2
  string = '154'
  
  ! Convert a string to a numeric value
  read (string,'(I10)') value
  print *, value
  
  ! Convert a value to a formatted string
  write (string2,'(I10)') value
  print *, string2
end program read_val

---

So I guess it is mostly a discussion, which format is prefered and what should be added like @milancurcic suggested.

[aman-godara]

How about we add 2 small sections in documentation with the name troubleshooting and caution?
We know not everyone has the patience to go through the whole documentation only to look for the solution to the problems they are facing with a particular function. If we add a small troubleshooting section and caution section (they are not needed for all functions though but for can be quite useful for some) it will make documentation way easier to reference to.

Also, sometimes Fortan throws bad errors, so the documentation can provide some possible ways in which a user can solve those errors. It will be like a small stackoverflow in itself.

Also, at places where a feature is quite large people divide documentation as per the use case like basic and advanced assuming that not everyone importing the feature is going to be a user looking for advanced usages.

[aman-godara]

Also, a contributor might not be aware of markdown which GitHub uses this too can be added.

in GitHub Flavoured Markdown:
Double space + Enter means new line. Double Enter also means new line.
space + Enter DOESN'T mean new line and means a single space only.
Single Enter means a single space
more than one space means a single space only.

Different websites support different markdown but mostly there is consensus.

These websites can help:
https://commonmark.org/help/tutorial/
https://guides.github.com/features/mastering-markdown/
https://www.markdownguide.org/basic-syntax/

[milancurcic]

I'd like to simplify and condense the spec as much as possible so the user doesn't have to scroll down a lot to get the full picture.

What do you all think about having a "Signature" section? For example for linspace, it would look something like this:

linspace

Description of linspace.

Signature

function linspace(start, end) result(res)
    real, intent(in) :: start
    real, intent(in) :: end
    real :: res(DEFAULT_LINSPACE_LENGTH)

function linspace(start, end, n) result(res)
    real, intent(in) :: start
    real, intent(in) :: end
    integer, intent(in) :: n
    real :: res(max(n, 0))

IMO there are a few advantages to this approach:

• You can see in one focused place all the arguments and types
• In the description of arguments, you don't need to write the types, ranks, and intent of arguments, which IMO is boilerplate when used in prose. Instead, you just focus on the meaning of arguments and results, and the types, ranks, and intent are apparent from the signature.
• We can remove the "Syntax" and "Class" sections. Both will be apparent from the signature. Class especially always seemed unnecessarily bureaucratic to me.

Then of course we have a question of how to represent signatures of generic procedures. For linspace, perhaps something like this:

function linspace(start, end) result(res)
    {real, integer}, intent(in) :: start
    real, intent(in) :: end
    real :: res(DEFAULT_LINSPACE_LENGTH)

Where curly braces include all compatible types. Or, just spell out all specific signatures.

Doing so for all type kinds would probably be overkill and flood the spec page, so perhaps we can simply have a sentence at the bottom of the signature section, saying something like:

All real arguments are compatible with sp, dp, and qp type kinds. All integer arguments are compatible with int8, int16, int32, and int64 arguments.

If you like this idea, let me know and I can prepare an alternative spec doc for one procedure so we can compare them side by side.

[gareth-nx]

@milancurcic Yes, to me this sounds like an improvement.

[JHenneberg]

@milancurcic : I agree. Especially about the generic routines. Your idea could be further extended. Instead of a text describing the KIND of datatype the signature could be shortened even more:

function linspace(start, end) result(res)
    {real( {sp, dp, qp} ), integer( {int8, int16} ), intent(in) :: start
    real( {sp, dp, qp} ), intent(in) :: end
    real :: res(DEFAULT_LINSPACE_LENGTH)

Negative effect would be of course that the KIND needs to be added to every parameter.

[milancurcic]

I put together a proposal template that could be used as a mold for all spec docs: https://github.com/milancurcic/stdlib-spec-template, with a few changes from the current specs, as described in this thread:

• Provide interfaces
• Remove "Syntax", "Class", and "Status" sections. The former two are redundant with the interface. I will explain about removing "Status" in a bit.
• "Arguments" section now doesn't list all the boilerplate that's already in the interface, but only describes the meaning.

To illustrate, I made an example spec following the proposed template. Compare it with the current version that we have.

Rationale on removing "Status" from the spec pages: While everything in stdlib is experimental, and it will be for the foreseeable future, we should simply state upfront in the README.md that everything is experimental, and unclutter the spec docs with unnecessary boilerplate. When we are ready to mark some procedures as stable, we should create a Status page where all the modules, procedures, and derived types will be listed with their statuses. But until then, having every single procedure spell out Status: Experimental on it doesn't communicate anything useful.

In summary, my motivation for this is to:

• Have a template that we can base current and future specs on and stay consistent, as proposed by @JHenneberg
• Significantly clean up the current specs and make them easier to read and use