@@ -174,6 +174,15 @@ class CodeStringsMarkdown(BaseModel):
174174
175175 @property
176176 def flat (self ) -> str :
177+ """Returns the combined Python module from all code blocks.
178+
179+ Each block is prefixed by a file path comment to indicate its origin.
180+ This representation is syntactically valid Python code.
181+
182+ Returns:
183+ str: The concatenated code of all blocks with file path annotations.
184+
185+ """
177186 if self ._cache .get ("flat" ) is not None :
178187 return self ._cache ["flat" ]
179188 self ._cache ["flat" ] = "\n " .join (
@@ -183,7 +192,15 @@ def flat(self) -> str:
183192
184193 @property
185194 def markdown (self ) -> str :
186- """Returns the markdown representation of the code, including the file path where possible."""
195+ """Returns a Markdown-formatted string containing all code blocks.
196+
197+ Each block is enclosed in a triple-backtick code block with an optional
198+ file path suffix (e.g., ```python:filename.py).
199+
200+ Returns:
201+ str: Markdown representation of the code blocks.
202+
203+ """
187204 return "\n " .join (
188205 [
189206 f"```python{ ':' + str (code_string .file_path ) if code_string .file_path else '' } \n { code_string .code .strip ()} \n ```"
@@ -192,6 +209,12 @@ def markdown(self) -> str:
192209 )
193210
194211 def file_to_path (self ) -> dict [str , str ]:
212+ """Return a dictionary mapping file paths to their corresponding code blocks.
213+
214+ Returns:
215+ dict[str, str]: Mapping from file path (as string) to code.
216+
217+ """
195218 if self ._cache .get ("file_to_path" ) is not None :
196219 return self ._cache ["file_to_path" ]
197220 self ._cache ["file_to_path" ] = {
@@ -201,6 +224,17 @@ def file_to_path(self) -> dict[str, str]:
201224
202225 @staticmethod
203226 def parse_markdown_code (markdown_code : str ) -> CodeStringsMarkdown :
227+ """Parse a Markdown string into a CodeStringsMarkdown object.
228+
229+ Extracts code blocks and their associated file paths and constructs a new CodeStringsMarkdown instance.
230+
231+ Args:
232+ markdown_code (str): The Markdown-formatted string to parse.
233+
234+ Returns:
235+ CodeStringsMarkdown: Parsed object containing code blocks.
236+
237+ """
204238 matches = markdown_pattern .findall (markdown_code )
205239 results = CodeStringsMarkdown ()
206240 for file_path , code in matches :
0 commit comments