ALDoc : Best practices for folder naming

[fvet]

Please include the following with each issue:

1. Describe the bug We would like to get some more insights on how ALDoc / Doxfx is generating the TOC for the documentation site. Our .al files are currenly organized into separate folder by logical domain / feature / library. We would like ALDoc to generate a similar table of contents, respecting this logical grouping.

I've however tried several setup but would like to get some recommendations of MS on how to best structure the files to get the desired ALDoc result.

PS: Seems like the system apps of MS also use \Src as subfolder, while the Base App does not and uses root folders by feature / namespace. PS 2: This applies to an app that does not apply namespaces yet.

2. To Reproduce

Scenario 1 (our current app structure)

• Current App has a \permission and \src folder, both containins ALL .al files
• The files in the \src folder are logically grouped in subfolders.
• The AlDoc results is not sufficient, as it only list permissions and src as Modules.

Scenario 2

• App's root folder contains different folders with .al files, logically grouped in folders.
• Result is quit OK (except several bugs of inproper ESCA folders)
• Downside is that source files are no longer grouped inside a separate folder (and are in between the Translations, Settings, ... folders)

Scenario 3

• App has one \src folder containins ALL .al files, logically grouped in folders.
• From a developers perspective, that would be a valid solution, as it isolates sources from other app folders such as Translations, Settings, ...
• The ALDoc does no longer respect / inherit the logical grouping

3. Expected behavior I'm looking for a solution / advice on having the logical app folder structure represented as Modules in the AL documentation.

5. Versions:

• AL Language: 13.0.864697

[hhfiddelke]

if you can't explain a structure to a trainee within 15 minutes, it is a bad structure in my opinion.

In my opinion the "Module" structure is not very useful, because many "modules" are overlapping, so you do not know where to place. And if this is the case every developer will handle it in his own way, which only causes chaos.

[fvet]

@esbenk Adding some more context based on below blog ... https://www.navnab.com/2023/09/03/generating-help-with-the-aldoc-tool/

... that came to the same conclusion

A) As-is repo structure

- .vscode
- scripts
- src                (containg al files)
  - A_Feature    (containg al files)
  - X_Feature    (containg al files)
- translations

B) Expected aldoc repo structure

- .vscode
- A_Feature (containg al files)
- translations
- scripts
- X_Feature (containg al files)

C) Expected table of contents

Modules
- A_Feature
- X_Feature

Question is if aldoc would be able to support folder structures from A), including a \src folder with subfolders by feature. If not, we might adopt a new guidelines to place folders by feature under the project's root folder instead.

Other findings: Tried to find a pattern in MS apps, but the System app does use a \src folder approach, while the Base Application does not...