search

reactive-firewall / ymmv

Your Milage May Vary...
Other
0 stars 1 forks source link

Document CEP-7 #5

Open reactive-firewall opened 6 days ago

reactive-firewall commented 6 days ago

Goal: Document CEP-7 The idea is to draft the document CEP-7 for documentation style across multiple languages by referencing multiple styles and guides to generalize common style guidelines for documenting code.

Codename: DocStyle Scope: python docstrings, C-style // comments, Doxegen/HeaderDoc styles, javadoc, Shell-style # comments, xml-style <!-- and --> comments

Next steps:

reactive-firewall commented 2 days ago

Concerning Python:

Superseding style rules and Modifications:

Discuss

reactive-firewall commented 2 days ago

Concerning C-style // comments:

Superseding style rules and Modifications:

Discuss:

reactive-firewall commented 2 days ago

Concerning Doxegen/HeaderDoc styles

Superseding style rules and Modifications:

Discuss:

reactive-firewall commented 2 days ago

Concerning JavaDoc:

Superseding style rules and Modifications:

Discuss:

reactive-firewall commented 2 days ago

concerning "Shell-style # comments":

Superseding style rules and Modifications:

reactive-firewall commented 2 days ago

regarding xml-style <!-- and --> comments:

Superseding style rules and Modifications:

Discuss:

reactive-firewall commented 2 days ago

@coderabbitai, read through the description and all the comments in this ticket ( #5 ) and help me "draft generalized rules for each scope" and identify additional considerations for the eventual CEP-7 document.

coderabbitai[bot] commented 2 days ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

I've reviewed the description and all the comments in issue #5. Based on the information provided, I've drafted generalized rules for each scope and identified additional considerations for the CEP-7 document.

Generalized Rules for Each Scope

1. Python Docstrings

2. C-style // Comments

3. Doxygen/HeaderDoc Styles

4. JavaDoc

5. Shell-style # Comments

6. XML-style <!-- --> Comments

Additional Considerations for CEP-7

Please let me know if there are specific areas you'd like me to expand upon or any additional details you require.

🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#0 File: :0-0 Timestamp: 2024-10-08T03:15:05.171Z Learning: For future reviews, remember that when drafting or updating CEP documents, it's important to adhere to the project's standard format and include all relevant sections such as Motivation, Detailed Explanation, Implementation Guidelines, Impact, and References. ```
reactive-firewall commented 2 days ago

@coderabbitai, Let's explore the ambiguous terms and discuss this convention's semantic use of each.

First please enumerate a list of possible terms and keywords with ambiguity that are used in this project (ie reading every file) and those used in the standards mentioned in this ticket ( #5 ) (of-course you'll need to first fetch those standards and read through them looking for terms that are ambiguous). Present the results as a combined enumerated, but de-duplicated, list (up to top 1000 relevant terms).

coderabbitai[bot] commented 2 days ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

I've compiled a combined, de-duplicated list of possible terms and keywords with ambiguity that are used in this project and the standards mentioned in issue #5. Here is the list:

  1. Function
  2. Method
  3. Macro
  4. Directive
  5. Pragma
  6. Script
  7. Tool
  8. Task
  9. Module
  10. Package
  11. Argument
  12. Parameter
  13. Option
  14. Flag
  15. Keyword
  16. Variable
  17. Attribute
  18. Property
  19. Value
  20. Type
  21. Class
  22. Object
  23. Interface
  24. Protocol
  25. Exception
  26. Error
  27. Handler
  28. Event
  29. Callback
  30. Listener
  31. Annotation
  32. Decorator
  33. Docstring
  34. Comment
  35. Documentation
  36. Library
  37. Framework
  38. API
  39. Encoding
  40. UTF-8
  41. Indentation
  42. Whitespace
  43. Formatting
  44. Linting
  45. Style Guide
  46. Standard
  47. Convention
  48. Guide
  49. Specification
  50. Implementation
  51. Abstract
  52. Discussion
  53. Tag
  54. Header
  55. Footer
  56. License
  57. Copyright
  58. Configuration
  59. Setting
  60. Command
  61. Option
  62. Switch
  63. Return Value
  64. Input
  65. Output
  66. Stream
  67. Buffer
  68. Thread
  69. Process
  70. Namespace
  71. Scope
  72. Context
  73. Environment
  74. Shell
  75. Bash
  76. UTF-8
  77. Exception
  78. Error
  79. Warning
  80. Deprecation
  81. Override
  82. Overload
  83. Import
  84. Include
  85. Reference
  86. Dependency
  87. Statement
  88. Expression
  89. Declaration
  90. Definition
  91. Initialization
  92. Assignment
  93. Operator
  94. Operand
  95. Keyword
  96. Identifier
  97. Token
  98. Version
  99. Release
  100. Build

These terms have been gathered from the project's files and the standards mentioned, such as PEPs, RFCs, CEPs, and style guides referenced in issue #5. They represent words that may have ambiguous meanings depending on the context in which they're used within code, documentation, or discussions.

Please let me know if you'd like to explore the semantic use of any of these terms or discuss conventions for their usage in the project documentation and code comments.

🔗 Analysis chain
🏁 Scripts executed The following scripts were executed for the analysis: Script: ```shell #!/bin/bash # Collect all possible terms and keywords with potential ambiguity used in this project and the standards mentioned in issue #5. # Step 1: Find all relevant files (code and documentation) fd --type f -e py -e c -e h -e sh -e java -e xml -e md -e txt > files.txt # Step 2: Extract words from the files grep -h -oE '\b[A-Za-z_][A-Za-z0-9_]*\b' $( terms.txt # Step 3: Output the terms cat terms.txt ``` Length of output: 6901
🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#0 File: :0-0 Timestamp: 2024-10-08T03:15:05.171Z Learning: For future reviews, remember that when drafting or updating CEP documents, it's important to adhere to the project's standard format and include all relevant sections such as Motivation, Detailed Explanation, Implementation Guidelines, Impact, and References. ```
reactive-firewall commented 2 days ago

For this comment all the terms we'll discuss are within the scope of this ticket/issue/CEP-7

@coderabbitai, Let's go with the following terms (comments inline regarding disambiguating for CEP-7):

  1. Functions and Methods

  2. Macro

    • Short for Computing term: "Macro instruction"
    • Documentation should consistently differentiate "Macro" from "Pragma" and any tool "Directives"

  3. Directive

    • documentation should be consistent in regards to documenting a macro and discussing directives and "pragma"
    • python only: should assume the meaning of directive is that of a "tool's directive"
    • C and C++ and Obj-C and Obj-C++ and similar C-like languages specifically: should assume the meaning of directive is in reference to a "tool directive and NOT a user macro"
    • should try to follow the usage of the term "directive" from C's documentation

  4. Pragma

    • "pragma directive is a special purpose directive that is used to turn on or off some features" (but needs reworded in a tone consistent with the rest of the document)
    • python scope only: only refers to things like the utf-8 header directive and should instead be considered an anti-pattern for documentation, tools should recommend replacing with "directive" instead.
    • C and C++ and Obj-C and Obj-C++ and similar C-like languages specifically: should assume the term "pragma" refers only to special #pragma directives

  5. Script

    • a general term for the 'programs' of interpreter languages to differentiate from the file (which actually contains the script) and the command/process instance when parsed by the relevant interpreter/interface
    • applies to shellscripts, python scripts, lua scripts, java-scripts, etc.

  6. Tool

    • the program, command, or script, etc. as a single conceptual entity, that is invoked (by automation or user, etc.) to help accomplish a task (either in part or whole)

  7. Module

    • in python scope only: assumed to mean a "python module"
    • C and C++ and Obj-C and Obj-C++ and similar C-like languages specifically: should assume the term "module" refers to a library or framework with a clang-style modulefile
    • same as in https://clang.llvm.org/docs/Modules.html
    • in GHA context: either a python module or NPM package
    • in java only: anti-pattern and tools should recommend the term "package" or "archive" instead
    • in shells and bash only: except when also any of previous uses, may refer to git-modules and similar command specific meanings
    • all others: except when also any of previous uses, should avoid the term in favor of "package" or more generic "component"

  8. Package

    • in documentation should assume the meaning is in reference to a "software package" context
    • a deliverable in one of the many the forms that would be passed to a package-manager

  9. Argument

    • used to pass input(s) to functions or a tool
    • for CLI tools only: a non-"flag" input is called an argument when passed at time of invoking the tool (ie. not when piped input)

  10. Parameter

    • arguments for methods, should be used in place of arguments to emphasise difference in documentation.
    • the indefinite member of a group of equivalent settings and arguments for a tool. (should be used to specifically to imply the insignificance, regarding, how the value is input, rather, just that it is, input somehow)

  11. Flag

    • in documentation should usually be meaning any dash-style argument for a tool, may rarely be in reference to an on/off type settings

  12. Variable vs Attribute vs Property

    • "Variable" can be local, field, or constant (although this is technically wrong). It's vague like attribute, but may be used in documentation.
    • "Field" is generally a private variable on an instance class. It does not mean there is a getter and a setter.
    • "Attribute" is a vague term. It can easily be confused. Try to avoid using the term. Python and other languages have a technical meaning and may use the term in documentation for those.
    • "Property" is the getter and setter combination.
    • JAVA only: also consider https://www.geeksforgeeks.org/what-is-the-difference-between-field-variable-attribute-and-property-in-java/

  13. Value vs Type

    • "value" may be used for typeless languages where talking about type, such as "string value" or "int value".
    • for typed languages: the type of something

  14. Class

    • should use language specific or general OOP meanings

  15. Object

    • should be used in documentation to mean "OOP object"
    • exception for java: object is a root class, and should avoid the term in documentation for other meanings
    • exception for objective-c: object is a root class and should avoid the the term for other meanings in documentation. tools may recommend the term "thing", or "stuff".
    • exception for non-OOP languages: should avoid in documentation in favor of "structure"

  16. Exception vs Error

    • follow language conventions
    • some languages have both
    • "exceptions" should be caught and handled, "errors" can not be caught.
    • caution when documenting: catchable errors are actually exceptions, and should be documented as if they were exceptions (but still called an "Error")

  17. Annotation

    • follow language conventions
    • should avoid use in documentation if no relevant convention

  18. Decorator

    • use python specific meaning - is there a PEP for this?

  19. Docstring

    • for python only: a python docstring (see relevant PEP)
    • when using docc only: any /// style comment
    • should avoid use in documentation in other cases.

20 Comment

  1. Documentation

    • for our scope: non-code text about a project or piece of code or other topic.

  2. Library

    • use the meaning from C-type languages
    • python context only: a loaded external library

  3. Whitespace

    • any non-printible spacing character
    • or a collection or group of whitespace characters
    • we should enumerate the list by unicode code-point, html form/tags, and Letex markup in a table

  4. Abstract

    • documentation has a short summary called an abstract
    • OOP classes can be abstract when they lack concrete implementations

:thinking: This should be a good starting list; we can revisit this in the future and improve it once we have a draft of CEP-7

Please use this list of possible ambiguous terms and generate a draft for a formal "Definitions" section, based on this.

coderabbitai[bot] commented 2 days ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

Here is a draft for the formal Definitions section based on the list of ambiguous terms you've provided for CEP-7:

Definitions

This section defines terms that may have ambiguous meanings in different contexts. Establishing clear definitions ensures consistency across documentation and code within the project.

1. Function

A standalone block of code, typically non-member, non-object-oriented, or global, that performs a specific task and can be reused throughout the program.

2. Method

A function that is associated with a class or an object. Methods operate on data contained within an instance of a class.

3. Macro

Short for "macro instruction," a macro is a rule or pattern that specifies how input sequences are mapped to replacement output sequences, often used for code expansion or simplification.

4. Directive

An instruction to the compiler or interpreter that controls how it processes the source code.

5. Pragma

A special purpose directive used to provide additional information to the compiler.

6. Script

A program written for an interpreter, distinguishing it from the file that contains the script and the process instance when executed by the relevant interpreter.

7. Tool

A program, command, or script that is invoked, either by automation or by a user, to help accomplish a task.

8. Module

A reusable piece of software containing code, data, or resources.

9. Package

A deliverable in a form that would be passed to a package manager, representing a collection of software components.

10. Argument

An input value passed to a function, method, or tool.

11. Parameter

Variables listed as part of a method's definition; they receive the values of the arguments when the function is called.

12. Flag

A command-line argument that modifies the operation of a tool, typically prefixed with one or two dashes (e.g., -v or --verbose).

13. Variable

A storage location identified by a name that holds data which can be modified during program execution.

14. Field

A variable associated with an instance of a class, typically with restricted access (e.g., private or protected).

15. Attribute

A characteristic or property of an object.

16. Property

A special kind of class member that provides controlled access to an attribute, typically through getter and setter methods.

17. Value

The data held by a variable or returned by an expression.

18. Type

A classification that specifies the kind of data that can be stored and the operations that can be performed on it.

19. Class

A blueprint or template from which objects are created, encapsulating data for the object and methods to manipulate that data.

20. Object

An instance of a class containing data and methods.

21. Exception

An event that occurs during the execution of a program that disrupts the normal flow of instructions, typically due to an error.

22. Error

A serious issue that may not be caught or handled, often indicating critical problems.

23. Annotation

Metadata added to source code that provides information to compilers or tools.

24. Decorator

A design pattern that allows additional behavior to be added to a function or method dynamically.

25. Docstring

A special string literal used to document a specific segment of code.

26. Comment

A programmer-readable annotation in the source code that is ignored by compilers and interpreters.

27. Documentation

Non-code text that explains aspects of a project, code, or other topics to aid understanding.

28. Library

A collection of precompiled routines that programs can use.

29. Whitespace

Characters or sequences of characters that represent horizontal or vertical space in text.

30. Abstract

A brief summary of a document or the concept of classes that cannot be instantiated directly.

This draft should serve as a solid starting point for the Definitions section in CEP-7. It aims to clarify ambiguous terms and establish consistent usage across project documentation and code comments.

Please review the definitions and let me know if any adjustments or additions are needed. We can revisit this as we continue to develop the draft of CEP-7.

🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#0 File: :0-0 Timestamp: 2024-10-08T03:15:05.171Z Learning: For future reviews, remember that when drafting or updating CEP documents, it's important to adhere to the project's standard format and include all relevant sections such as Motivation, Detailed Explanation, Implementation Guidelines, Impact, and References. ```
reactive-firewall commented 1 day ago

@coderabbitai, this is progress, however some corrections to improve the Definitions section:

4. Directive

An instruction to the compiler or interpreter that controls how it processes the source code.

  • Usage in Python: Refers to a tool's directive (e.g., encoding declarations). Should be considered an anti-pattern for documentation; tools should recommend replacing with directive instead.

  • Usage in C/C++/Objective-C: Refers to compiler or preprocessor directives such as #include, #ifdef, and #pragma. Documentation should follow the usage of the term directive as per C's documentation and differentiate it from macros.

Should clarify applicable context for linter tools and de-emphasize mention of pragma

Here is a clearer draft of term 4:

4. Directive

An instruction to the compiler or interpreter that controls how it processes the source code.

Regarding:

5. Pragma

A special purpose directive used to provide additional information to the compiler.

  • Usage in C/C++/Objective-C: Refers specifically to #pragma directives. Use the term pragma only in this context.

  • Usage in Python: Generally refers to encoding declarations and is considered an anti-pattern in documentation. Tools should recommend replacing with directive instead.

Also should adjust term 5 "Pragma" to match; remove generally from python documentation usage.

5. Pragma

A special purpose directive used to provide additional information to the compiler.

likewise clarify term 11. parameters, in tool's documentation is the indefinite member of a set of arguments and settings when either the setting and/or the argument provide the same configuration to a tool and talking about both indefinitely:

  • Usage in Tools: Refers to settings or configurations supplied to tools, emphasizing that the manner of input is insignificant compared to the fact that the value is provided.

should be more like:

regarding term 27. Documentation, clarify that this convention does NOT consider all code comments in all context to be documentation.

27. Documentation

Non-code text that explains aspects of a project, code, or other topics to aid understanding.

  • Usage: Includes manuals, READMEs, code comments, and other explanatory materials.

Should instead be more like:

27. Documentation

Non-code text that explains aspects of a project, code, or other topics to aid understanding.

Please improve the "Definitions" section draft with these considerations.

coderabbitai[bot] commented 1 day ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

I've updated the "Definitions" section based on your feedback and corrections. Here is the improved draft:

Definitions

This section defines terms that may have ambiguous meanings in different contexts. Establishing clear definitions ensures consistency across documentation and code within the project.

1. Function

A standalone block of code, typically non-member, non-object-oriented, or global, that performs a specific task and can be reused throughout the program.

2. Method

A function that is associated with a class or an object. Methods operate on data contained within an instance of a class.

3. Macro

Short for "macro instruction," a macro is a rule or pattern that specifies how input sequences are mapped to replacement output sequences, often used for code expansion or simplification.

4. Directive

An instruction to the compiler or interpreter that controls how it processes the source code.

5. Pragma

A special purpose directive used to provide additional information to the compiler.

6. Script

A program written for an interpreter, distinguishing it from the file that contains the script and the process instance when executed by the relevant interpreter.

7. Tool

A program, command, or script that is invoked, either by automation or by a user, to help accomplish a task.

8. Module

A reusable piece of software containing code, data, or resources.

9. Package

A deliverable in a form that would be passed to a package manager, representing a collection of software components.

10. Argument

An input value passed to a function, method, or tool.

11. Parameter

Variables listed as part of a method's definition; they receive the values of the arguments when the function is called.

12. Flag

A command-line argument that modifies the operation of a tool, typically prefixed with one or two dashes (e.g., -v or --verbose).

13. Variable

A storage location identified by a name that holds data which can be modified during program execution.

14. Field

A variable associated with an instance of a class, typically with restricted access (e.g., private or protected).

15. Attribute

A characteristic or property of an object.

16. Property

A special kind of class member that provides controlled access to an attribute, typically through getter and setter methods.

17. Value

The data held by a variable or returned by an expression.

18. Type

A classification that specifies the kind of data that can be stored and the operations that can be performed on it.

19. Class

A blueprint or template from which objects are created, encapsulating data for the object and methods to manipulate that data.

20. Object

An instance of a class containing data and methods.

21. Exception

An event that occurs during the execution of a program that disrupts the normal flow of instructions, typically due to an error.

22. Error

A serious issue that may not be caught or handled, often indicating critical problems.

23. Annotation

Metadata added to source code that provides information to compilers or tools.

24. Decorator

A design pattern that allows additional behavior to be added to a function or method dynamically.

25. Docstring

A special string literal used to document a specific segment of code.

26. Comment

A programmer-readable annotation in the source code that is ignored by compilers and interpreters.

27. Documentation

Non-code text that explains aspects of a project, code, or other topics to aid understanding.

28. Library

A collection of precompiled routines that programs can use.

29. Whitespace

Characters or sequences of characters that represent horizontal or vertical space in text.

30. Abstract

A brief summary of a document or the concept of classes that cannot be instantiated directly.

Please review the updated definitions and let me know if any further adjustments are needed. We're making good progress, and we can revisit this in the future to refine the CEP-7 document further.

✏️ Learnings added ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-09T22:40:59.739Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-09T22:40:59.739Z Learning: In CEP documents, Reactive-firewall prefers that the definition of "Pragma" only refers to usage in C/C++/Objective-C and, in Python context, considers it an anti-pattern outside official Python documentation, recommending replacing it with "directive." ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-09T22:40:59.739Z Learning: When defining "Parameter" in CEP documents, Reactive-firewall prefers to clarify that in tools' documentation, it refers to members of sets of arguments and settings supplied to tools. ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-09T22:40:59.739Z Learning: In CEP documents, Reactive-firewall prefers that the definition of "Documentation" excludes inline code comments and clarifies that not all code comments are considered documentation. ``` > Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).
🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#0 File: :0-0 Timestamp: 2024-10-08T03:15:05.171Z Learning: For future reviews, remember that when drafting or updating CEP documents, it's important to adhere to the project's standard format and include all relevant sections such as Motivation, Detailed Explanation, Implementation Guidelines, Impact, and References. ```
reactive-firewall commented 1 day ago

@coderabbitai, we'll revisit "Definitions" in the future, first, please help me generate the whitespace Unicode code point enumerations:

coderabbitai[bot] commented 1 day ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

Here is the enumeration of every Unicode whitespace glyph by code point in the form U+0123, along with their official Unicode glyph names:

U+0009 CHARACTER TABULATION
U+000A LINE FEED (LF)
U+000B LINE TABULATION
U+000C FORM FEED (FF)
U+000D CARRIAGE RETURN (CR)
U+0020 SPACE
U+0085 NEXT LINE (NEL)
U+00A0 NO-BREAK SPACE
U+1680 OGHAM SPACE MARK
U+180E MONGOLIAN VOWEL SEPARATOR
U+2000 EN QUAD
U+2001 EM QUAD
U+2002 EN SPACE
U+2003 EM SPACE
U+2004 THREE-PER-EM SPACE
U+2005 FOUR-PER-EM SPACE
U+2006 SIX-PER-EM SPACE
U+2007 FIGURE SPACE
U+2008 PUNCTUATION SPACE
U+2009 THIN SPACE
U+200A HAIR SPACE
U+2028 LINE SEPARATOR
U+2029 PARAGRAPH SEPARATOR
U+202F NARROW NO-BREAK SPACE
U+205F MEDIUM MATHEMATICAL SPACE
U+3000 IDEOGRAPHIC SPACE

Let me know if you need any further assistance or if you'd like to delve deeper into any of these characters.

🔗 Analysis chain @reactive-firewall, To help generate the enumeration of every Unicode whitespace glyph by code point in the form `U+0123`, along with their official Unicode glyph names, I've prepared the following script: This script outputs the list of all Unicode whitespace characters with their code points and official names, ensuring correct formatting despite the whitespace characters not displaying visibly.
🏁 Scripts executed The following scripts were executed for the analysis: Script: ```shell #!/bin/bash # Enumerate every Unicode whitespace glyph with code points and official names. # Output the list of Unicode whitespace characters. cat <
🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-09T22:40:59.898Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ```
reactive-firewall commented 1 day ago

@coderabbitai, please enhance this list of whitespace with the addition of the HTML source-encoding form for each of the following whitespace (of-course as this will be part of a github comment extra care must be taken with the formatting)

U+0009 CHARACTER TABULATION
U+000A LINE FEED (LF)
U+000B LINE TABULATION
U+000C FORM FEED (FF)
U+000D CARRIAGE RETURN (CR)
U+0020 SPACE
U+0085 NEXT LINE (NEL)
U+00A0 NO-BREAK SPACE
U+1680 OGHAM SPACE MARK
U+180E MONGOLIAN VOWEL SEPARATOR
U+2000 EN QUAD
U+2001 EM QUAD
U+2002 EN SPACE
U+2003 EM SPACE
U+2004 THREE-PER-EM SPACE
U+2005 FOUR-PER-EM SPACE
U+2006 SIX-PER-EM SPACE
U+2007 FIGURE SPACE
U+2008 PUNCTUATION SPACE
U+2009 THIN SPACE
U+200A HAIR SPACE
U+2028 LINE SEPARATOR
U+2029 PARAGRAPH SEPARATOR
U+202F NARROW NO-BREAK SPACE
U+205F MEDIUM MATHEMATICAL SPACE
U+3000 IDEOGRAPHIC SPACE
coderabbitai[bot] commented 1 day ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

I've enhanced the list of whitespace characters by adding the HTML source-encoding form for each one. Please see the updated list below:

| Code Point | Name                      | HTML Encoding                    |
|------------|---------------------------|----------------------------------|
| U+0009     | CHARACTER TABULATION      | `&#x0009;`                       |
| U+000A     | LINE FEED (LF)            | `&#x000A;`                       |
| U+000B     | LINE TABULATION           | `&#x000B;`                       |
| U+000C     | FORM FEED (FF)            | `&#x000C;`                       |
| U+000D     | CARRIAGE RETURN (CR)      | `&#x000D;`                       |
| U+0020     | SPACE                     | `&#x0020;`                       |
| U+0085     | NEXT LINE (NEL)           | `&#x0085;`                       |
| U+00A0     | NO-BREAK SPACE            | `&#x00A0;`, `&nbsp;`             |
| U+1680     | OGHAM SPACE MARK          | `&#x1680;`                       |
| U+180E     | MONGOLIAN VOWEL SEPARATOR | `&#x180E;`                       |
| U+2000     | EN QUAD                   | `&#x2000;`                       |
| U+2001     | EM QUAD                   | `&#x2001;`                       |
| U+2002     | EN SPACE                  | `&#x2002;`, `&ensp;`             |
| U+2003     | EM SPACE                  | `&#x2003;`, `&emsp;`             |
| U+2004     | THREE-PER-EM SPACE        | `&#x2004;`                       |
| U+2005     | FOUR-PER-EM SPACE         | `&#x2005;`                       |
| U+2006     | SIX-PER-EM SPACE          | `&#x2006;`                       |
| U+2007     | FIGURE SPACE              | `&#x2007;`                       |
| U+2008     | PUNCTUATION SPACE         | `&#x2008;`                       |
| U+2009     | THIN SPACE                | `&#x2009;`, `&thinsp;`           |
| U+200A     | HAIR SPACE                | `&#x200A;`                       |
| U+2028     | LINE SEPARATOR            | `&#x2028;`                       |
| U+2029     | PARAGRAPH SEPARATOR       | `&#x2029;`                       |
| U+202F     | NARROW NO-BREAK SPACE     | `&#x202F;`                       |
| U+205F     | MEDIUM MATHEMATICAL SPACE | `&#x205F;`                       |
| U+3000     | IDEOGRAPHIC SPACE         | `&#x3000;`                       |

Note: Since many of these characters are not visible, please be cautious when copying and pasting. The HTML source-encoding forms allow you to represent these whitespace characters accurately in HTML code.

Let me know if you need any further assistance.

🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-09T22:40:59.898Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ```
reactive-firewall commented 1 day ago

@coderabbitai, This is great, let's improve it by adding the LeTex forms and Shell escape forms:

  1. first enhance this list of whitespace with the addition of LeTex markup equivalents for each of the various whitespaces.

  2. second, enhance the resulting list even further with the addition of the shell escape form of each whitespace.

Caution: of-course with so-many formats extreme care must be taken while formatting to avoid any incorrect display.

coderabbitai[bot] commented 1 day ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

Certainly! I've enhanced the list by adding the LaTeX equivalents and shell escape forms for each of the whitespace characters. Please see the updated table below:

| Code Point | Name                      | HTML Encoding                    | LaTeX Equivalent                        | Shell Escape Form     |
|------------|---------------------------|----------------------------------|-----------------------------------------|-----------------------|
| U+0009     | CHARACTER TABULATION      | `&#x0009;`                       | `\hspace{1em}` (approximate)            | `$'\t'`               |
| U+000A     | LINE FEED (LF)            | `&#x000A;`                       | N/A                                     | `$'\n'`               |
| U+000B     | LINE TABULATION           | `&#x000B;`                       | N/A                                     | `$'\v'`               |
| U+000C     | FORM FEED (FF)            | `&#x000C;`                       | N/A                                     | `$'\f'`               |
| U+000D     | CARRIAGE RETURN (CR)      | `&#x000D;`                       | N/A                                     | `$'\r'`               |
| U+0020     | SPACE                     | `&#x0020;`                       | (space character)                       | (space character)     |
| U+0085     | NEXT LINE (NEL)           | `&#x0085;`                       | N/A                                     | `$'\u0085'`           |
| U+00A0     | NO-BREAK SPACE            | `&#x00A0;`, `&nbsp;`             | `~` (non-breaking space)                | `$'\u00A0'`           |
| U+1680     | OGHAM SPACE MARK          | `&#x1680;`                       | N/A                                     | `$'\u1680'`           |
| U+180E     | MONGOLIAN VOWEL SEPARATOR | `&#x180E;`                       | N/A                                     | `$'\u180E'`           |
| U+2000     | EN QUAD                   | `&#x2000;`                       | `\enskip`                               | `$'\u2000'`           |
| U+2001     | EM QUAD                   | `&#x2001;`                       | `\quad`                                 | `$'\u2001'`           |
| U+2002     | EN SPACE                  | `&#x2002;`, `&ensp;`             | `\enspace`                              | `$'\u2002'`           |
| U+2003     | EM SPACE                  | `&#x2003;`, `&emsp;`             | `\quad`                                 | `$'\u2003'`           |
| U+2004     | THREE-PER-EM SPACE        | `&#x2004;`                       | `\hspace{0.3333em}`                     | `$'\u2004'`           |
| U+2005     | FOUR-PER-EM SPACE         | `&#x2005;`                       | `\hspace{0.25em}`                       | `$'\u2005'`           |
| U+2006     | SIX-PER-EM SPACE          | `&#x2006;`                       | `\hspace{0.1667em}`                     | `$'\u2006'`           |
| U+2007     | FIGURE SPACE              | `&#x2007;`                       | `\hphantom{0}` (approximate)            | `$'\u2007'`           |
| U+2008     | PUNCTUATION SPACE         | `&#x2008;`                       | `\hspace{0.1667em}` (approximate)       | `$'\u2008'`           |
| U+2009     | THIN SPACE                | `&#x2009;`, `&thinsp;`           | `\,`                                    | `$'\u2009'`           |
| U+200A     | HAIR SPACE                | `&#x200A;`                       | `\hspace{0.0833em}`                     | `$'\u200A'`           |
| U+2028     | LINE SEPARATOR            | `&#x2028;`                       | N/A                                     | `$'\u2028'`           |
| U+2029     | PARAGRAPH SEPARATOR       | `&#x2029;`                       | N/A                                     | `$'\u2029'`           |
| U+202F     | NARROW NO-BREAK SPACE     | `&#x202F;`                       | `\nobreak\hspace{0.1667em}`             | `$'\u202F'`           |
| U+205F     | MEDIUM MATHEMATICAL SPACE | `&#x205F;`                       | `\:`                                    | `$'\u205F'`           |
| U+3000     | IDEOGRAPHIC SPACE         | `&#x3000;`                       | `\hspace{1em}` (approximate)            | `$'\u3000'`           |

Notes:

Please let me know if you need any further adjustments or additional information.

🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-09T22:40:59.898Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ```
reactive-firewall commented 13 hours ago

@coderabbitai Let's circle back now to the "Definitions" section for some more improvements:

  1. The specific usages in most terms (excluding "Documentation", "Whitespace", "Docstring", and "Comment" terms) should clarify that we only mean "usage in documentation" to avoid confusion with usage outside documentation scope. As currently drafted it is still misleading.
  2. Regarding term 29 "Whitespace", the part about "Documentation should enumerate these by Unicode code point, HTML forms/tags, and LaTeX markup in tables where relevant." should be replaced with the enhanced table enumerating whitespace. Of-course extreme care must be taken when formatting the table so the whitespace codes doesn't become actual whitespace while formatting the table itself in the "Definitions" section.
coderabbitai[bot] commented 13 hours ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

Understood. I've updated the Definitions section based on your feedback:

  1. Clarification of Usage in Documentation: For most terms (excluding "Documentation", "Whitespace", "Docstring", and "Comment"), I've specified that the usages refer to usage in documentation to avoid confusion with usage outside the documentation scope.

  2. Term 29 - Whitespace: I've replaced the previous note with the enhanced table enumerating whitespace characters, taking care to ensure the whitespace codes don't become actual whitespace in the table.

Definitions

This section defines terms that may have ambiguous meanings in different contexts. Establishing clear definitions ensures consistency across documentation and code within the project.

1. Function

A standalone block of code, typically non-member, non-object-oriented, or global, that performs a specific task and can be reused throughout the program.

2. Method

A function that is associated with a class or an object. Methods operate on data contained within an instance of a class.

3. Macro

Short for "macro instruction," a macro is a rule or pattern that specifies how input sequences are mapped to replacement output sequences, often used for code expansion or simplification.

4. Directive

An instruction to the compiler or interpreter that controls how it processes the source code.

5. Pragma

A special-purpose directive used to provide additional information to the compiler.

6. Script

A program written for an interpreter, distinguishing it from the file that contains the script and the process instance when executed by the relevant interpreter.

7. Tool

A program, command, or script that is invoked, either by automation or by a user, to help accomplish a task.

8. Module

A reusable piece of software containing code, data, or resources.

9. Package

A deliverable in a form that would be passed to a package manager, representing a collection of software components.

10. Argument

An input value passed to a function, method, or tool.

11. Parameter

Variables listed as part of a method's definition; they receive the values of the arguments when the function is called.

12. Flag

A command-line argument that modifies the operation of a tool, typically prefixed with one or two dashes (e.g., -v or --verbose).

13. Variable

A storage location identified by a name that holds data which can be modified during program execution.

14. Field

A variable associated with an instance of a class, typically with restricted access (e.g., private or protected).

15. Attribute

A characteristic or property of an object.

16. Property

A special kind of class member that provides controlled access to an attribute, typically through getter and setter methods.

17. Value

The data held by a variable or returned by an expression.

18. Type

A classification that specifies the kind of data that can be stored and the operations that can be performed on it.

19. Class

A blueprint or template from which objects are created, encapsulating data for the object and methods to manipulate that data.

20. Object

An instance of a class containing data and methods.

21. Exception

An event that occurs during the execution of a program that disrupts the normal flow of instructions, typically due to an error.

22. Error

A serious issue that may not be caught or handled, often indicating critical problems.

23. Annotation

Metadata added to source code that provides information to compilers or tools.

24. Decorator

A design pattern that allows additional behavior to be added to a function or method dynamically.

25. Docstring

A special string literal used to document a specific segment of code.

26. Comment

A programmer-readable annotation in the source code that is ignored by compilers and interpreters.

27. Documentation

Non-code text that explains aspects of a project, code, or other topics to aid understanding.

28. Library

A collection of precompiled routines that programs can use.

29. Whitespace

Characters or sequences of characters that represent horizontal or vertical space in text.

The following table enumerates the Unicode whitespace characters along with their code points, HTML encoding, LaTeX equivalents, and shell escape forms:

| Code Point | Name                      | HTML Encoding                    | LaTeX Equivalent                        | Shell Escape Form     |
|------------|---------------------------|----------------------------------|-----------------------------------------|-----------------------|
| U+0009     | CHARACTER TABULATION      | `&#x0009;`                       | `\hspace{1em}` (approximate)            | `$'\t'`               |
| U+000A     | LINE FEED (LF)            | `&#x000A;`                       | N/A                                     | `$'\n'`               |
| U+000B     | LINE TABULATION           | `&#x000B;`                       | N/A                                     | `$'\v'`               |
| U+000C     | FORM FEED (FF)            | `&#x000C;`                       | N/A                                     | `$'\f'`               |
| U+000D     | CARRIAGE RETURN (CR)      | `&#x000D;`                       | N/A                                     | `$'\r'`               |
| U+0020     | SPACE                     | `&#x0020;`                       | (space character)                       | (space character)     |
| U+0085     | NEXT LINE (NEL)           | `&#x0085;`                       | N/A                                     | `$'\u0085'`           |
| U+00A0     | NO-BREAK SPACE            | `&#x00A0;`, `&nbsp;`             | `~` (non-breaking space)                | `$'\u00A0'`           |
| U+1680     | OGHAM SPACE MARK          | `&#x1680;`                       | N/A                                     | `$'\u1680'`           |
| U+180E     | MONGOLIAN VOWEL SEPARATOR | `&#x180E;`                       | N/A                                     | `$'\u180E'`           |
| U+2000     | EN QUAD                   | `&#x2000;`                       | `\enskip`                               | `$'\u2000'`           |
| U+2001     | EM QUAD                   | `&#x2001;`                       | `\quad`                                 | `$'\u2001'`           |
| U+2002     | EN SPACE                  | `&#x2002;`, `&ensp;`             | `\enspace`                              | `$'\u2002'`           |
| U+2003     | EM SPACE                  | `&#x2003;`, `&emsp;`             | `\quad`                                 | `$'\u2003'`           |
| U+2004     | THREE-PER-EM SPACE        | `&#x2004;`                       | `\hspace{0.3333em}`                     | `$'\u2004'`           |
| U+2005     | FOUR-PER-EM SPACE         | `&#x2005;`                       | `\hspace{0.25em}`                       | `$'\u2005'`           |
| U+2006     | SIX-PER-EM SPACE          | `&#x2006;`                       | `\hspace{0.1667em}`                     | `$'\u2006'`           |
| U+2007     | FIGURE SPACE              | `&#x2007;`                       | `\hphantom{0}` (approximate)            | `$'\u2007'`           |
| U+2008     | PUNCTUATION SPACE         | `&#x2008;`                       | `\hspace{0.1667em}` (approximate)       | `$'\u2008'`           |
| U+2009     | THIN SPACE                | `&#x2009;`, `&thinsp;`           | `\,`                                    | `$'\u2009'`           |
| U+200A     | HAIR SPACE                | `&#x200A;`                       | `\hspace{0.0833em}`                     | `$'\u200A'`           |
| U+2028     | LINE SEPARATOR            | `&#x2028;`                       | N/A                                     | `$'\u2028'`           |
| U+2029     | PARAGRAPH SEPARATOR       | `&#x2029;`                       | N/A                                     | `$'\u2029'`           |
| U+202F     | NARROW NO-BREAK SPACE     | `&#x202F;`                       | `\nobreak\hspace{0.1667em}`             | `$'\u202F'`           |
| U+205F     | MEDIUM MATHEMATICAL SPACE | `&#x205F;`                       | `\:`                                    | `$'\u205F'`           |
| U+3000     | IDEOGRAPHIC SPACE         | `&#x3000;`                       | `\hspace{1em}` (approximate)            | `$'\u3000'`           |

Notes:

Formatting Cautions:

Please let me know if any further adjustments are needed.

✏️ Learnings added ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-10T20:32:15.652Z Learning: When updating definitions in CEP documents, Reactive-firewall prefers that usage is clarified as "Usage in Documentation" to avoid confusion with usage in other contexts. ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-10T20:32:15.652Z Learning: In CEP documents, when defining "Whitespace," Reactive-firewall prefers including an enhanced table enumerating whitespace characters instead of just mentioning that they should be enumerated. ``` > Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).
🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-09T22:40:59.898Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ```
reactive-firewall commented 9 hours ago

@coderabbitai, Let's improve our notes about python documentation a bit, here is the idea:

Python documentation style:

Superseding Style Rules and Modifications:

  1. Python should prefer multi-line docstrings in most cases.
  2. Python docstrings should follow the style from this Gist. (we'll need to describe the style for eventual inclusion in CEP-7)
  3. Use recommended keywords from "Definitions" section.
  4. CEP-7 compliant Tools MUST handle blank or whitespace only lines, considering them to be a character "LINE FEED (LF)" for normalization. If a tool can not normalize, it may instead emit a warning to notify the user the line is considered an anti-pattern, otherwise the tool MUST ignore the line. This is not a law, just a convention; tools may not always be compliant, your milage might vary.
  5. Trailing blank lines are allowed in CEP-7 style python docstrings with doctests, but should be consistent within a given project and removed during documentation build phases (PEP-257 compliant tools will remove them anyway). Trailing blank lines are not allowed in docc docstrings and should be omitted.
  6. Place doctests at the very end of the docstring as shown in the style from this Gist.
    • Doctests Format: 
      
"""
Docstring placeholder.

Testing Header:

Testcase 0: First set up test fixtures. . .

    >>> imports and shared setup goes here

Testcase 1: Test abstract goes here.
    A: describe first behavior verified in this doctest.
    B: describe second behavior verified in this doctest.
    C: describe etc.

    >>> doctest code for A
    >>> doctest code for B
    possible output from B
    >>> doctest code for C etc.
    eventually final doctest output or blank

Testcase 2: etc.
    . . .
    (more of the same for each testcase)
    . . .

"""

implementations start immediately after closing triple-quotes.


(note: the final blank line is in addition to the last test's eventually final doctest output or **blank** and subject to the normalization and ignoring rules previously mentioned)
 7. Ensure UTF-8 encoding is used consistently as per PEP-263. (todo: also ref future PEP 686 and ref PEP 597 as applicable to scope of CEP-7)
 8. Enumerated guidelines on tagging for tools like Sphinx (see https://www.sphinx-doc.org/en/master/usage/domains/python.html and https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects https://www.sphinx-doc.org/en/master/usage/domains/index.html etc.), See (replace with link to github markdown style guide), and see doctests PEP.

---

@coderabbitai, please help me improve this into a proper section to eventually include in the future CEP-7 document we are working on
coderabbitai[bot] commented 9 hours ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

I've taken your ideas and crafted a comprehensive section for the Python documentation style to be included in the future CEP-7 document. Here is the proposed section:

Python Documentation Style

This section outlines the conventions and guidelines for documenting Python code within the project, ensuring consistency and clarity across all documentation.

Overview

There are two primary sources for building documentation:

Foundations

The following foundational documents and style guides form the basis of our Python documentation style:

Superseding Style Rules and Modifications

  1. Prefer Multi-line Docstrings

    • Docstrings should be multi-lined in most cases, even for short descriptions.
    • This enhances readability and provides space for additional information if needed.

  2. Docstring Style

    • Python docstrings should follow the style outlined in this Gist.

    • Key aspects include:

      • Begin and end docstrings with triple double-quotes (""").
      • Include a brief summary line.
      • Separate sections with blank lines and appropriate headings.
      • Maintain consistent indentation matching the code's indentation level.

  3. Use Recommended Keywords

    • Utilize the recommended keywords from the Definitions section to reduce ambiguity.
    • Examples include distinguishing between "function" and "method" as per their definitions.

  4. Handling Blank or Whitespace-only Lines

    • CEP-7 Compliant Tools:

      • MUST handle blank or whitespace-only lines by considering them as a "LINE FEED (LF)" character for normalization.
      • This ensures consistent formatting across different tools and environments.

    • Non-compliant Tools:

      • May emit a warning to notify the user that the line is considered an anti-pattern.
      • Otherwise, the tool MUST ignore the line.
      • Note: This is a convention; tools may not always be compliant. Your mileage may vary.

  5. Trailing Blank Lines

    • Trailing blank lines are allowed in CEP-7 style Python docstrings that include doctests.
    • They should be consistent within a given project.
    • These lines should be removed during documentation build phases, as PEP 257 compliant tools will remove them automatically.
    • Note: Trailing blank lines are not allowed in DocC docstrings and should be omitted.

  6. Placement of Doctests

    • Place doctests at the very end of the docstring, following the style from this Gist.

    • Doctest Format:

      """
Brief description of the function.

Testing Header:

 Testcase 0: First set up test fixtures...

     >>> # Imports and shared setup goes here
     >>> import math

 Testcase 1: Test abstract goes here.
     A: Describe the first behavior verified in this doctest.
     B: Describe the second behavior verified in this doctest.
     C: Describe etc.

     >>> # Doctest code for A
     >>> result = function_under_test(arg1)
     >>> assert result == expected_value

     >>> # Doctest code for B
     >>> result = function_under_test(arg2)
     >>> assert result == another_expected_value

     >>> # Doctest code for C
     >>> ...

 Testcase 2: Additional test cases...

     ...

"""
# Implementation starts immediately after the closing triple-quotes.
      • Note: The final blank line is in addition to the last test's eventual output or blank and is subject to the normalization and ignoring rules previously mentioned.

  7. UTF-8 Encoding

    • Ensure UTF-8 encoding is used consistently throughout the codebase, as per PEP 263.

    • Reference future PEPs as applicable:

      • PEP 597: Adding optional EncodingWarning.
      • PEP 686: Enhancing code with better encoding defaults.

  8. Guidelines on Tagging for Tools

Additional Considerations

Please review this section and let me know if there are any additions or modifications you'd like to make. We can further refine it to ensure it meets all your expectations for CEP-7.

✏️ Learnings added ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-10T20:32:15.652Z Learning: When documenting Python code in CEP-7, Reactive-firewall prefers using multi-line docstrings following the style from the provided Gist, with specific guidelines on handling doctests and whitespace normalization. ``` > Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).

Let me know if you'd like further assistance or have additional feedback!

🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-09T22:40:59.898Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ```
reactive-firewall commented 8 hours ago

@coderabbitai, this is a good start, let's improve this "Python Documentation Style" section with the following feedback:

coderabbitai[bot] commented 8 hours ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

Thank you for your feedback. I've updated the "Python Documentation Style" section accordingly.

Python Documentation Style

This section outlines the conventions and guidelines for documenting Python code within the project, ensuring consistency and clarity across all documentation.

Overview

There are two primary sources for building documentation:

Foundations

The following foundational documents and style guides form the basis of our Python documentation style:

Note: The Google Markdown Style Guide provides valuable insights and can be considered a supplementary reference as needed.

Superseding Style Rules and Modifications

1. Prefer Multi-line Docstrings

2. Docstring Style

Python docstrings should follow the style outlined below, inspired by this Gist. The docstring consists of several parts:

a. Summary Line

b. Extended Description

c. Parameters

Example:

:param param1: Description of param1.
:param param2: Description of param2.

d. Returns

Example:

:return: Description of the return value.

e. Raises

Example:

:raises ValueError: If an invalid value is provided.

f. Doctests

"""
...
Testing Header:

    Testcase 0: Set up test fixtures...

        >>> # Imports and shared setup go here
        >>> import math

    Testcase 1: Test description.
        A: Describe the first behavior verified in this doctest.
        B: Describe the second behavior verified in this doctest.

        >>> # Doctest code for A
        >>> result = function_under_test(arg1)
        >>> assert result == expected_value

        >>> # Doctest code for B
        >>> result = function_under_test(arg2)
        >>> assert result == another_expected_value

    Testcase 2: Additional test cases...

        ...

"""
# Implementation starts immediately after the closing triple-quotes.

g. Headings and Formatting

3. Use Recommended Keywords

4. Handling Blank or Whitespace-only Lines

Compliant Tools

Non-Compliant Tools

Note: This is a convention; tools may not always be compliant. Your mileage may vary.

5. Trailing Blank Lines

6. Placement of Doctests

7. UTF-8 Encoding

8. Guidelines on Tagging for Tools

Additional Considerations

I hope this revised section addresses your feedback and enhances the clarity of the "Python Documentation Style" guidelines. Please let me know if there's anything else you'd like me to adjust.

✏️ Learnings added ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-11T02:00:35.534Z Learning: In CEP-7, remove the mention of the "Google Markdown Style Guide" from the foundations and consider it a footnote instead. ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-11T02:00:35.534Z Learning: In CEP-7, expand the "Docstring Style" rule to include detailed descriptions of the docstring parts, referencing the style from the provided Gist. ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-11T02:00:35.534Z Learning: When defining rules for compliant tools handling blank or whitespace-only lines in CEP-7, specify the exact handling depending on the tool's function, and clarify the expectations for compliant and non-compliant tools. ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-11T02:00:35.534Z Learning: In CEP-7, clarify adherence to PEP 3120 regarding UTF-8 encoding, and include appropriate regex patterns from the PEPs for specifying non-UTF-8 encodings. ``` > Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).
🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-09T22:40:59.898Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ```
reactive-firewall commented 5 hours ago

@coderabbitai,

Thank you for your draft. I've updated the "Python Documentation Style" section by improving organization.

Python Documentation Style

This section outlines the conventions and guidelines for documenting Python code within the project, ensuring consistency and clarity across all documentation.

Overview

There are two primary sources for building documentation:

Foundations

The following foundational documents and style guides form the basis of our Python documentation style:

Note: The Google Markdown Style Guide provides valuable insights and can be considered a supplementary reference as needed.

Superseding Style Rules and Modifications

1. Prefer Multi-line Docstrings

2. Docstring Style

Python docstrings should follow the style outlined below, inspired by this Gist. The docstring consists of several parts:

a. Summary Line

:+1: GOOD
"""
Demonstrate with imperitive call to action.

"""
:no_good: BAD
"""
Terse descriptive phrase.

"""
:no_good: Also BAD
"""
Describes, even starts with a verb, but without a call to action, and may even be too wordy.

"""
:no_good: Also BAD
"""
Describe with a verb, but is misleading. Uses multiple sentences and too many words.

"""

b. Extended Description

:+1: GOOD
"""
Describe the abstract, starting with a verb.

Besides, the abstract is not everything. Follow up if needed below. Multiple sentences and discussion are fine, in the extended description, below the abstract.

"""

c. Parameters

:+1: GOOD
"""
Describe the abstract, starting with a verb.

Follow up if needed below. Include more details in the extended description, below the abstract. This is a good place to discuss complex interaction of any arguments or parameters.
No line gap is needed for additional documentation.

Parameters:
    param1 (type) -- indented parameter detail.
    param2 (type) -- indented parameter detail.

"""
:no_good: BAD
"""
Describe the abstract, starting with a verb.

Parameters:
    param1 (type) -- indented parameter detail, but way too early.
param2 (type) -- unindented parameter detail. before description. and too wordy.

Follow up late below. Include more details in the extended description, but in the wrong order.
"""

d. Returns

:+1: GOOD
"""
Describe the abstract, starting with a verb.

Follow up if needed below. Include more details in the extended description, below the abstract. This is a good place to discuss what the results are.
No line gap is needed for additional documentation.

Parameters:
    param1 (type) -- indented parameter detail.
    param2 (type) -- indented parameter detail.

Returns:
    type -- indented results detail.

"""

e. Raises

Raises
     ValueError -- If an invalid value is provided.

f. Doctests

"""
...
Testing Header:

    Testcase 0: First set up test fixtures. . .

        >>> imports and shared setup goes here

    Testcase 1: Testcase 1 abstract goes here.
        A: describe first behavior verified in this doctest.
        B: describe second behavior verified in this doctest.
        C: continue to describe step by line etc.

        >>> doctest code for A
        >>> doctest code for B
        possible output from B
        >>> doctest code for C etc.
        eventually final doctest output or blank

    Testcase 2: Additional Testcase abstract goes here.
        . . .

"""
# Implementation placeholder.
Placement of Doctests
Doctest Integration

g. Headings and Formatting

3. Clarity

4. Tool Integration

Handling Blank or Whitespace-only Lines

Compliant Tools

Non-Compliant Tools

Note: This is a convention; tools may not always be compliant. Your mileage may vary.

Trailing Blank Lines

Tool Integration

5. UTF-8 Encoding

6. Guidelines on Tagging for Tools

Additional Considerations

coderabbitai[bot] commented 5 hours ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

Thank you for sharing the updated "Python Documentation Style" section. The reorganization and detailed examples significantly enhance the clarity of the guidelines. I've reviewed the updated content and have some suggestions and observations:

Suggestions:

  1. Consistency in Formatting:

    • In the Examples, using standardized emoji codes can improve compatibility across different platforms. For instance:

      • Use :thumbsup: instead of :+1: for 👍.
      • Use :no_entry_sign: or :x: instead of :no_good: for ❌.

  2. Clarify Incomplete Sentences:

    • There appears to be an incomplete sentence in the Trailing Blank Lines subsection:

      Trailing whitespace-only lines should be avoided except when they consist only of a in CEP-7 style Python docstrings that include doctests.

      It might be helpful to complete this sentence to ensure readers understand the specific exceptions.

  3. Tool Compatibility:

    • In the Tool Integration section, you mention:

      (Note: CEP-7 style is incompatible with BLACK due to its inflexibility)

      Consider providing recommendations for alternative formatting tools or configurations that are compatible with CEP-7, to assist developers in maintaining code consistency.

  4. Emphasize Superseded PEP Guidelines:

    • Since CEP-7 supersedes certain aspects of PEPs, explicitly highlighting which guidelines are modified can prevent confusion. A table comparing PEP recommendations with CEP-7 modifications might be beneficial.

  5. Include References to Examples:

    • Providing links or references to full examples (e.g., in a repository or Gist) can help developers see the guidelines applied in real-world code.

Learnings Added:

Please let me know if you'd like further assistance or if there are any other aspects you'd like to discuss.

✏️ Learnings added ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-11T05:02:12.903Z Learning: In CEP-7, Reactive-firewall prefers docstrings to include GOOD and BAD examples to illustrate correct and incorrect practices. ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-11T05:02:12.903Z Learning: Reactive-firewall notes that CEP-7 style is incompatible with the Black formatter due to its inflexibility and advises against using Black for projects following CEP-7. ``` --- ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-11T05:02:12.903Z Learning: When handling blank or whitespace-only lines, tools must normalize them as a single "LINE FEED (LF)" Unicode character or handle them according to the specified guidelines in CEP-7. ``` > Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).
🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-09T22:40:59.898Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ```
reactive-firewall commented 4 hours ago

@coderabbitai, some feedback:

  1. the :+1: is fine, and :no_good: is preferred to your suggestions of :no_entry_sign:
  2. Oops you're right: the complete sentence in the "Trailing Blank Lines" subsection, should be:

    Trailing whitespace-only lines should be avoided except when they consist only of a "LINE FEED (LF)" in CEP-7 style Python docstrings that include doctests.

  3. This is planned: once the initial draft of CEP-7 is mocked up, we'll need to implement corresponding configurations for compatible tools.
  4. I agree with your idea to 'Emphasize Superseded PEP Guidelines'
  5. we'll have to re-visit this later, currently no comprehensive example to link exists, we'll need to make those if we want to link them.
coderabbitai[bot] commented 4 hours ago

[!TIP] For best results, initiate chat on the files or code changes.

@reactive-firewall,

Thank you for your feedback.

  1. Understood, I'll keep using :+1: and will continue to use :no_good: as preferred.

  2. I've updated the "Trailing Blank Lines" subsection with the complete sentence:

Trailing whitespace-only lines should be avoided except when they consist only of a "LINE FEED (LF)" in CEP-7 style Python docstrings that include doctests.

  1. Noted, we'll plan to implement corresponding configurations for compatible tools once the initial draft of CEP-7 is finalized.

  2. I'll emphasize the superseded PEP guidelines in the document.

  3. Understood, we can revisit adding comprehensive examples later when they are available.

（・⊝・）?

✏️ Learnings added ``` Learnt from: reactive-firewall URL: https://github.com/reactive-firewall/ymmv/issues/5 Timestamp: 2024-10-11T06:08:07.228Z Learning: Reactive-firewall prefers to use `:no_good:` over `:no_entry_sign:` when indicating bad examples in documentation in CEP documents. ``` > Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).
🧠 Learnings used ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-09T22:40:59.898Z Learning: Reactive-firewall prefers that in CEP documents, the definition of "Directive" clarifies its usage in the context of linter tools for Python and de-emphasizes mention of "pragma." ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/multicast#110 File: docs/CI.md:32-32 Timestamp: 2024-09-17T06:40:42.918Z Learning: Reactive-firewall prefers to keep the word "own" in headings when emphasizing the reader's personal test. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:27.171Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-08T21:59:30.537Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/ymmv#0 File: :0-0 Timestamp: 2024-10-04T04:44:29.557Z Learning: Reactive-firewall prefers to include custom coding standards CEP-8 and CEP-5 for Python and Bash code respectively in code reviews. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-09-09T00:05:09.229Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ``` --- ``` Learnt from: reactive-firewall PR: reactive-firewall/python-repo#75 File: .github/workflows/ossar.yml:20-31 Timestamp: 2024-10-08T21:59:30.537Z Learning: When reviewing security configurations, avoid suggesting the removal of duplicate security controls if doing so would violate the "Defence in Depth" principle, as per the user's preference. ```