Documentation guidelines #12

wojpok · 2025-05-24T09:02:36Z

No description provided.

KR338 · 2025-05-26T08:44:02Z

src/conv/documentation.md

+closing marker of a multiline comment can appear either on a separate line or
+immediately after the final line of the docstring body.
+
+During the process of generting doc pages, all docstring are concatenated 


Suggested change

During the process of generting doc pages, all docstring are concatenated

During the process of generating doc pages, all docstring are concatenated

KR338 · 2025-05-26T08:47:59Z

src/conv/documentation.md

+  @param f Folding function. Receives an additional index argument.
+  @param xs List to be folded.
+
+  @returns The result of iterativately applied folding operation.


Suggested change

@returns The result of iterativately applied folding operation.

@returns The result of the iteratively applied folding operation.

KR338

Further spell check/proofread

KR338 · 2025-05-26T08:50:06Z

src/conv/documentation.md

+
+During the process of generting doc pages, all docstring are concatenated 
+to a single, continuous markdown file. Even though it is possible, we advise
+against splitting markdown constructs like tables across multiple docstring.


Suggested change

against splitting markdown constructs like tables across multiple docstring.

against splitting markdown constructs like tables across multiple docstrings.

KR338 · 2025-05-26T08:50:48Z

src/conv/documentation.md

+If applied to empty list, it calls implicit function `~onError`. 
+It also allows overriding the starting value of the iterator index `i`.
+
+Even though, the type is quite ellaborate, documentation is straightforward.


Suggested change

Even though, the type is quite ellaborate, documentation is straightforward.

Even though, the type is quite elaborate, documentation is straightforward.

KR338 · 2025-05-26T08:51:47Z

src/conv/documentation.md

+### Int64 
+
+`Int64` is a builtin type, which means that the there is no declaration
+of this type in Prelude. Fortunatelly, scoping allows us to add docstring


Suggested change

of this type in Prelude. Fortunatelly, scoping allows us to add docstring

of this type in Prelude. Fortunately, scoping allows us to add docstring

KR338 · 2025-05-26T08:53:03Z

src/conv/documentation.md

+## # Main header
+
+{##
+  This is an example docstring with markdown table:


Suggested change

This is an example docstring with markdown table:

This is an example docstring with a markdown table:

KR338 · 2025-05-26T08:54:17Z

src/conv/documentation.md

+be written separately and explicitly linked to the intended code element using
+an identifier.
+
+In such cases, docstrings are mandatorily multiline and apropriete identifiers


Suggested change

In such cases, docstrings are mandatorily multiline and apropriete identifiers

In such cases, docstrings are mandatorily multiline and apropriate identifiers

Brychlikov

Some grammar mistakes.

Brychlikov · 2025-05-26T09:01:02Z

src/conv/documentation.md

+to that definition. The first continuous block of text is treated as a brief
+description. After an empty line, a more detailed explanation may be added.
+
+Additionally `@param`, `@asserts` and `@return` labels are supported in


Suggested change

Additionally `@param`, `@asserts` and `@return` labels are supported in

Additionally, `@param`, `@asserts`, and `@return` labels are supported in

We use Oxford commas everywhere in dbl comments, so let's keep things consistent

Brychlikov · 2025-05-26T09:02:57Z

src/conv/documentation.md

+
+## Guidelines
+
+To ensure good and consistent quality, follow specified these guidelines:


Suggested change

To ensure good and consistent quality, follow specified these guidelines:

To ensure good and consistent quality, follow these guidelines:

Brychlikov · 2025-05-26T09:04:50Z

src/conv/documentation.md

+- Sentences should be written in Present Simple tense,
+  although sometimes it is necessary to deviate from that.
+- End every sentence with a period.
+- Avoid using function name as noun and verb in the same sentence.


Suggested change

- Avoid using function name as noun and verb in the same sentence.

- Avoid using the function name as a noun and a verb in the same sentence.

Brychlikov · 2025-05-26T09:05:33Z

src/conv/documentation.md

+  although sometimes it is necessary to deviate from that.
+- End every sentence with a period.
+- Avoid using function name as noun and verb in the same sentence.
+  Specifically don't write descriptions like "`map` maps ..." and 


Suggested change

Specifically don't write descriptions like "`map` maps ..." and

Specifically, don't write descriptions like "`map` maps ..." and

Brychlikov · 2025-05-26T09:06:32Z

src/conv/documentation.md

+If applied to empty list, it calls implicit function `~onError`. 
+It also allows overriding the starting value of the iterator index `i`.
+
+Even though, the type is quite ellaborate, documentation is straightforward.


Suggested change

Even though, the type is quite ellaborate, documentation is straightforward.

Even though the type is quite elaborate, documentation is straightforward.

Brychlikov · 2025-05-26T09:08:06Z

src/conv/documentation.md

+  Folds list into a single value, using the last element of list as the initial
+  accumulator and passing index of each processed element.
+
+  Allows overriding initial value of iterator. When applied
+  to empty list, calls implicit `~onError` function.


Suggested change

Folds list into a single value, using the last element of list as the initial

accumulator and passing index of each processed element.

Allows overriding initial value of iterator. When applied

to empty list, calls implicit `~onError` function.

Folds the list into a single value, using the last element of list as the initial

accumulator and passing index of each processed element.

Allows overriding the initial value of the iterator. When applied

to an empty list, calls implicit `~onError` function.

Documentation guidelines

6a43a56

KR338 reviewed May 26, 2025

View reviewed changes

KR338 suggested changes May 26, 2025

View reviewed changes

KR338 mentioned this pull request May 26, 2025

Docs for the entire List module #11

Closed

Brychlikov suggested changes May 26, 2025

View reviewed changes

	During the process of generting doc pages, all docstring are concatenated
	During the process of generating doc pages, all docstring are concatenated

	@returns The result of iterativately applied folding operation.
	@returns The result of the iteratively applied folding operation.

	against splitting markdown constructs like tables across multiple docstring.
	against splitting markdown constructs like tables across multiple docstrings.

	Even though, the type is quite ellaborate, documentation is straightforward.
	Even though, the type is quite elaborate, documentation is straightforward.

	of this type in Prelude. Fortunatelly, scoping allows us to add docstring
	of this type in Prelude. Fortunately, scoping allows us to add docstring

	This is an example docstring with markdown table:
	This is an example docstring with a markdown table:

	In such cases, docstrings are mandatorily multiline and apropriete identifiers
	In such cases, docstrings are mandatorily multiline and apropriate identifiers

	Additionally `@param`, `@asserts` and `@return` labels are supported in
	Additionally, `@param`, `@asserts`, and `@return` labels are supported in


		## Guidelines

		To ensure good and consistent quality, follow specified these guidelines:

	- Avoid using function name as noun and verb in the same sentence.
	- Avoid using the function name as a noun and a verb in the same sentence.

	Specifically don't write descriptions like "`map` maps ..." and
	Specifically, don't write descriptions like "`map` maps ..." and

	Even though, the type is quite ellaborate, documentation is straightforward.
	Even though the type is quite elaborate, documentation is straightforward.

Documentation guidelines #12

Are you sure you want to change the base?

Documentation guidelines #12

Uh oh!

Conversation

wojpok commented May 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KR338 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Brychlikov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants