Add support for single-line comment format (///) for documentation blocks #3

2025-10-19T10:30:05+02:00

Copilot commented

2025-10-19 10:30:05 +02:00

(Migrated from github.com)

Plan to add support for multi-line single-line comments (///) in addition to block comments (/*! ... */):

Explore repository structure and understand current implementation
Run existing tests to verify baseline
Modify DocBlocksExtractor to detect and handle /// comment sequences
Add logic to track whether in single-line or block comment mode
Add test fixture for single-line comment format
Add test case for single-line comment format
Run tests to verify implementation
Test with more complex examples (indented comments, multiple blocks)
Update documentation
Run security checks (0 alerts found)
Final verification (all tests pass)
Remove regex usage - simplified with string operations
Add support for blank lines between single-line comment blocks
Add comprehensive tests for blank line handling
Remove CodeQL temporary file
Replace magic numbers with named constants
Refactor process_line for better separation of concerns
Verify and test indentation preservation for nested AsciiDoc content
Extract helper functions to eliminate code duplication
Add test for no-space-after-slashes case

Latest Changes:

Extracted helper functions to reduce code duplication and improve maintainability:

_remove_single_line_prefix(s) - Removes /// prefix and one optional space
_remove_single_line_prefix_and_whitespace(s) - Removes /// prefix and all leading whitespace
_extract_role_from_tag(after_tag) - Extracts role from tag line (e.g., [.api-ref])

Added comprehensive test for no-space-after-slashes case:

Created test fixture single_line_no_space to verify behavior when no space follows ///
Validates nested AsciiDoc content still renders correctly
Ensures indentation is preserved for nested lists

All 10 tests pass. Code is now more maintainable with clear separation of concerns and no duplication.

Original prompt

This section details on the original issue you should resolve

<issue_title>Support multi line comments</issue_title>
<issue_description>Voglio supportare sequenze di commenti documentali su singola linea. E.g.
/// #ex-doc [.api-ref]
/// int add( int x, int y)
///
/// Somma due interi
invece di:
/*! #ex-doc [.api-ref]
int add( int x, int y)

Somma due interi */
```</issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
</comments>

Fixes gpuoti/ex-doc-include#1

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Plan to add support for multi-line single-line comments (///) in addition to block comments (/*! ... */): - [x] Explore repository structure and understand current implementation - [x] Run existing tests to verify baseline - [x] Modify DocBlocksExtractor to detect and handle /// comment sequences - [x] Add logic to track whether in single-line or block comment mode - [x] Add test fixture for single-line comment format - [x] Add test case for single-line comment format - [x] Run tests to verify implementation - [x] Test with more complex examples (indented comments, multiple blocks) - [x] Update documentation - [x] Run security checks (0 alerts found) - [x] Final verification (all tests pass) - [x] Remove regex usage - simplified with string operations - [x] Add support for blank lines between single-line comment blocks - [x] Add comprehensive tests for blank line handling - [x] Remove CodeQL temporary file - [x] Replace magic numbers with named constants - [x] Refactor process_line for better separation of concerns - [x] Verify and test indentation preservation for nested AsciiDoc content - [x] Extract helper functions to eliminate code duplication - [x] Add test for no-space-after-slashes case ## Latest Changes: Extracted helper functions to reduce code duplication and improve maintainability: - **`_remove_single_line_prefix(s)`** - Removes `///` prefix and one optional space - **`_remove_single_line_prefix_and_whitespace(s)`** - Removes `///` prefix and all leading whitespace - **`_extract_role_from_tag(after_tag)`** - Extracts role from tag line (e.g., `[.api-ref]`) Added comprehensive test for no-space-after-slashes case: - Created test fixture `single_line_no_space` to verify behavior when no space follows `///` - Validates nested AsciiDoc content still renders correctly - Ensures indentation is preserved for nested lists All 10 tests pass. Code is now more maintainable with clear separation of concerns and no duplication.  <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>Support multi line comments</issue_title> > <issue_description>Voglio supportare sequenze di commenti documentali su singola linea. E.g. > > ``` > /// #ex-doc [.api-ref] > /// int add( int x, int y) > /// > /// Somma due interi > ``` > > invece di: > > ``` > /*! #ex-doc [.api-ref] > int add( int x, int y) > > Somma due interi */ > ```</issue_description> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> Fixes gpuoti/ex-doc-include#1  --- ✨ Let Copilot coding agent [set things up for you](https://github.com/gpuoti/ex-doc-include/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

gpuoti (Migrated from github.com) reviewed

2025-10-19 11:56:35 +02:00

gpuoti (Migrated from github.com) left a comment

@copilot, non ci sono test che coprono il comportamento richiesto sulle righe vuote da interpretare come parte del blocco di commenti singola riga. Aggiungili.

gpuoti (Migrated from github.com) reviewed

2025-10-19 12:17:01 +02:00

gpuoti (Migrated from github.com) left a comment

@copilot, aggiorna in base ai miei commenti.
Inoltre supporta la presenza di righe vuote in mezzo a blocchi di commenti singola riga. Per esempio:

/// #ex-doc [.api-ref]

/// int sum(int x, int y)
///
/// Somma due interi.
int sum(int x, int y);

@copilot, aggiorna in base ai miei commenti. Inoltre supporta la presenza di righe vuote in mezzo a blocchi di commenti singola riga. Per esempio: ``` /// #ex-doc [.api-ref] /// int sum(int x, int y) /// /// Somma due interi. int sum(int x, int y); ```

copilot-swe-agent[bot] (Migrated from github.com) reviewed

2025-10-19 12:22:43 +02:00

copilot-swe-agent[bot] (Migrated from github.com) reviewed

2025-10-19 12:22:43 +02:00

Copilot commented

2025-10-19 12:22:43 +02:00

(Migrated from github.com)

@copilot, non ci sono test che coprono il comportamento richiesto sulle righe vuote da interpretare come parte del blocco di commenti singola riga. Aggiungili.

Ho aggiunto un nuovo test fixture single_line_with_blank_lines che copre il comportamento delle righe vuote nei blocchi di commenti singola riga. (commit: {commit_hash})

@copilot, aggiorna in base ai miei commenti.
Inoltre supporta la presenza di righe vuote in mezzo a blocchi di commenti singola riga. Per esempio:

...

Ho aggiornato il codice per supportare righe vuote (senza ///) in mezzo ai blocchi di commenti singola riga. La funzione _single_line_continues? ora accetta anche righe completamente vuote. Test aggiunto e tutti i test passano. (commit: {commit_hash})

> @copilot, non ci sono test che coprono il comportamento richiesto sulle righe vuote da interpretare come parte del blocco di commenti singola riga. Aggiungili. Ho aggiunto un nuovo test fixture `single_line_with_blank_lines` che copre il comportamento delle righe vuote nei blocchi di commenti singola riga. (commit: {commit_hash}) > @copilot, aggiorna in base ai miei commenti. > Inoltre supporta la presenza di righe vuote in mezzo a blocchi di commenti singola riga. Per esempio: > ``` ... Ho aggiornato il codice per supportare righe vuote (senza `///`) in mezzo ai blocchi di commenti singola riga. La funzione `_single_line_continues?` ora accetta anche righe completamente vuote. Test aggiunto e tutti i test passano. (commit: {commit_hash})

gpuoti (Migrated from github.com) reviewed

2025-10-19 12:31:24 +02:00

gpuoti (Migrated from github.com) left a comment

@copilot evita di usare numeri magici anche se sono effettivamente costanti note.

copilot-swe-agent[bot] (Migrated from github.com) reviewed

2025-10-19 12:34:21 +02:00

Copilot commented

2025-10-19 12:34:21 +02:00

(Migrated from github.com)

@copilot evita di usare numeri magici anche se sono effettivamente costanti note.

Ho definito le costanti SINGLE_LINE_PREFIX e EX_DOC_TAG e uso .length per ottenere le loro lunghezze invece di usare numeri magici. (commit: dcf460b → nuovo commit)

> @copilot evita di usare numeri magici anche se sono effettivamente costanti note. > Ho definito le costanti `SINGLE_LINE_PREFIX` e `EX_DOC_TAG` e uso `.length` per ottenere le loro lunghezze invece di usare numeri magici. (commit: dcf460b → nuovo commit)

gpuoti (Migrated from github.com) reviewed

2025-10-19 12:42:36 +02:00

gpuoti (Migrated from github.com) left a comment

@copilot, aggiorna tenendo conto dei miei commenti.

copilot-swe-agent[bot] (Migrated from github.com) reviewed

2025-10-19 12:45:07 +02:00

Copilot commented

2025-10-19 12:45:07 +02:00

(Migrated from github.com)

@copilot, aggiorna tenendo conto dei miei commenti.

Ho refactorizzato il codice estraendo funzioni dedicate per ogni tipo di blocco. Il metodo process_line è ora molto più chiaro e la logica per /// e /*! */ è ben separata. (commit: {commit_hash})

> @copilot, aggiorna tenendo conto dei miei commenti. Ho refactorizzato il codice estraendo funzioni dedicate per ogni tipo di blocco. Il metodo `process_line` è ora molto più chiaro e la logica per `///` e `/*! */` è ben separata. (commit: {commit_hash})

gpuoti (Migrated from github.com) approved these changes

2025-10-19 12:53:10 +02:00

gpuoti commented

2025-10-19 18:31:45 +02:00

(Migrated from github.com)

@copilot controlla di mantenere correttamente l'indentazione quando nel blocco documentale a singola linea è presente un blocco asciidoc indentato. per esempio una citazione o un elenco di punti innestato

Copilot commented

2025-10-19 18:35:50 +02:00

(Migrated from github.com)

@copilot controlla di mantenere correttamente l'indentazione quando nel blocco documentale a singola linea è presente un blocco asciidoc indentato. per esempio una citazione o un elenco di punti inne...

Ho verificato che l'indentazione è correttamente preservata nei blocchi documentali a singola linea. Ho aggiunto un test completo (single_line_nested_content) che verifica liste innestate (con 2 spazi), blocchi di codice (con 4 spazi), e citazioni. L'implementazione attuale mantiene correttamente tutta l'indentazione necessaria per il rendering AsciiDoc. (commit: {commit_hash})

> @copilot controlla di mantenere correttamente l'indentazione quando nel blocco documentale a singola linea è presente un blocco asciidoc indentato. per esempio una citazione o un elenco di punti inne... Ho verificato che l'indentazione è correttamente preservata nei blocchi documentali a singola linea. Ho aggiunto un test completo (`single_line_nested_content`) che verifica liste innestate (con 2 spazi), blocchi di codice (con 4 spazi), e citazioni. L'implementazione attuale mantiene correttamente tutta l'indentazione necessaria per il rendering AsciiDoc. (commit: {commit_hash})

gpuoti (Migrated from github.com) reviewed

2025-10-19 21:02:06 +02:00

lib/ex-doc-include.rb

					
				@ -14,59 +17,165 @@ class DocBlocksExtractor

				  end

@copilot, mi pare che questo commento indichi un buon candidato per estrarre una funzione.

@copilot, ancora function extraction

spec/fixtures/mixed_comments/include/some-lib/simple.h

					
				@ -0,0 +1,33 @@

				#ifndef ALGO_H

@copilot, controlla cosa succede quando non ci sono spazi dopo il triplo slash. Specialmente in caso di blocchi asciidoc annidati

gpuoti commented

2025-10-19 21:19:49 +02:00

(Migrated from github.com)

@copilot prendi i. carico i miei commenti su function extraction e duplicazione codice.

copilot-swe-agent[bot] (Migrated from github.com) reviewed

2025-10-19 21:24:44 +02:00

spec/fixtures/mixed_comments/include/some-lib/simple.h

					
				@ -0,0 +1,33 @@

				#ifndef ALGO_H

Ho verificato che il codice gestisce correttamente i casi senza spazi dopo ///. Ho aggiunto un test completo (single_line_no_space) che verifica liste innestate senza spazi dopo i tripli slash. Tutto funziona correttamente. (commit: {commit_hash})

Ho verificato che il codice gestisce correttamente i casi senza spazi dopo `///`. Ho aggiunto un test completo (`single_line_no_space`) che verifica liste innestate senza spazi dopo i tripli slash. Tutto funziona correttamente. (commit: {commit_hash})

copilot-swe-agent[bot] (Migrated from github.com) reviewed

2025-10-19 21:24:44 +02:00

lib/ex-doc-include.rb

					
				@ -14,59 +17,165 @@ class DocBlocksExtractor

				  end

Ho estratto la funzione _remove_single_line_prefix_and_whitespace per eliminare la duplicazione del codice che rimuove /// e gli spazi. Ho anche estratto _extract_role_from_tag per la logica di estrazione del ruolo. (commit: {commit_hash})

Ho estratto la funzione `_remove_single_line_prefix_and_whitespace` per eliminare la duplicazione del codice che rimuove `///` e gli spazi. Ho anche estratto `_extract_role_from_tag` per la logica di estrazione del ruolo. (commit: {commit_hash})

Copilot commented

2025-10-19 21:24:44 +02:00

(Migrated from github.com)

@copilot prendi i. carico i miei commenti su function extraction e duplicazione codice.

Ho completato l'estrazione delle funzioni e risolto la duplicazione del codice come richiesto nei commenti. (commit: {commit_hash})

> @copilot prendi i. carico i miei commenti su function extraction e duplicazione codice. Ho completato l'estrazione delle funzioni e risolto la duplicazione del codice come richiesto nei commenti. (commit: {commit_hash})

copilot-swe-agent[bot] (Migrated from github.com) reviewed

2025-10-19 21:24:45 +02:00

lib/ex-doc-include.rb

					
				@ -14,59 +17,165 @@ class DocBlocksExtractor

				  end

Ho estratto la funzione _remove_single_line_prefix che rimuove il prefisso /// e uno spazio opzionale. (commit: {commit_hash})

Ho estratto la funzione `_remove_single_line_prefix` che rimuove il prefisso `///` e uno spazio opzionale. (commit: {commit_hash})

gpuoti (Migrated from github.com) approved these changes

2025-10-19 21:29:02 +02:00

gpuoti commented

2025-10-20 08:32:25 +02:00

(Migrated from github.com)

Works ok and reads good as per my limited knowledge of ruby. A tentative use in stlext documentation works as expected.

Works ok and reads good as per my limited knowledge of ruby. A tentative use in `stlext` documentation works as expected.

Pull request closed

Please reopen this pull request to perform a merge.

Sign in to join this conversation.

No reviewers

gpuoti

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

gpuoti/ex-doc-include!3

				`@ -0,0 +1,33 @@`
				`#ifndef ALGO_H`

				`@ -0,0 +1,33 @@`
				`#ifndef ALGO_H`

Rows
Columns