docs: update the documentation

Author: TendTo

README.md

@@ -150,7 +150,7 @@ doxygen(
         "*.h",          # Usually includes the source files and the markdown files.
         "*.cpp",
     ]) + ["README.md"],
-    # Additionally, you can use the `deps` attribute to select a target 
+    # Additionally, you can use the `deps` attribute to select a target
     # and automatically include all of the files in its `srcs`, `hdrs`, and `data` attributes,
     # along with all of its transitive dependencies.
     # deps = [":my_cc_target"],
@@ -177,6 +177,73 @@ They will simply be appended at the end of the file, overriding the default valu
 > [!Note]
 > See the [documentation](docs/doxygen_doc.md) for more information or the [examples](examples) directory for examples of how to use the rules.
 
+### Differences between `srcs` and `deps`
+
+The `srcs` and `deps` attributes work differently, and are not interchangeable.
+
+`srcs` is a list of files that will be passed to Doxygen for documentation generation.
+You can use `glob` to include a collection of multiple files.  
+On the other hand, if you indicate a target (e.g., `:my_genrule`), it will include all the files produced by that target.
+More precisely, the files in the DefaultInfo provider the target returns.
+Hence, when the documentation is generated, all rules in the `srcs` attribute **will** be built, and the files they output will be passed to Doxygen.
+
+On the other hand, `deps` is a list of targets whose sources will be included in the documentation generation.
+It will automatically include all the files in the `srcs`, `hdrs`, and `data` attributes of the target, and the same applies to all of its transitive dependencies, recursively.
+Since we are only interested in the source files, the `deps` targets **will not** be built when the documentation is generated.
+
+```bzl
+# My BUILD.bazel file
+load("@doxygen//:doxygen.bzl", "doxygen")
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+cc_library(
+    name = "lib",
+    hdrs = ["add.h", "sub.h"],
+    srcs = ["add.cpp", "sub.cpp"],
+)
+
+cc_library(
+    name = "main",
+    srcs = ["main.cpp"],
+    deps = [":lib"],
+)
+
+
+genrule(
+    name = "section",
+    outs = ["Section.md"],
+    cmd = """
+        echo "# Section " > $@
+        echo "This is some amazing documentation with section!!  " >> $@
+        echo "Incredible." >> $@
+    """,
+)
+
+doxygen(
+    name = "doxygen",
+    project_name = "dependencies",
+
+    # The output of the genrule will be included in the documentation.
+    # The genrule will be executed when the documentation is generated.
+    srcs = [
+        "README.md",  # file
+        ":section",  # genrule
+
+        # WARNING: By adding this, the main target will be built
+        # and only the output file `main.o` will be passed to Doxygen,
+        # which is likely not what you want.
+        # ":main"
+    ],
+
+    # The sources of the main target and its dependencies will be included.
+    # No compilation will be performed, so compile error won't be reported.
+    deps = [":main"],  # cc_library
+
+    # Always starts at the root folder
+    use_mdfile_as_mainpage = "dependencies/README.md",
+)
+```
+
 ## Build
 
 To build the documentation, run the following command:

doxygen/doxygen.bzl

@@ -123,14 +123,14 @@ doxygen(
 """,
     implementation = _doxygen_impl,
     attrs = {
-        "srcs": attr.label_list(allow_files = True, doc = "The source files to generate documentation for. Can include header files, source files, and any other file Doxygen can parse."),
-        "deps": attr.label_list(aspects = [collect_files_aspect], doc = "The dependencies targets whose files in their 'src', 'hdrs' and 'data' attributes will be collected to generate the documentation. Transitive dependencies are also taken into account."),
+        "srcs": attr.label_list(allow_files = True, doc = "List of source files to generate documentation for. Can include any file that Doxygen can parse, as well as targets that return a DefaultInfo provider (usually genrules). Since we are only considering the outputs files and not the sources, these targets **will** be built if necessary."),
+        "deps": attr.label_list(aspects = [collect_files_aspect], doc = "List of dependencies targets whose files present in the 'src', 'hdrs' and 'data' attributes will be collected to generate the documentation. Transitive dependencies are also taken into account. Since we are only considering the source files and not the outputs, these targets **will not** be built"),
         "configurations": attr.string_list(doc = "Additional configuration parameters to append to the Doxyfile. For example, to set the project name, use `PROJECT_NAME = example`."),
-        "outs": attr.string_list(default = ["html"], allow_empty = False, doc = """The output folders to keep. If only the html outputs is of interest, the default value will do. Otherwise, a list of folders to keep is expected (e.g. `["html", "latex"]`)."""),
+        "outs": attr.string_list(default = ["html"], allow_empty = False, doc = """Output folders to keep. If only the html outputs is of interest, the default value will do. Otherwise, a list of folders to keep is expected (e.g. `["html", "latex"]`)."""),
         "doxyfile_template": attr.label(
             allow_single_file = True,
             default = Label(":Doxyfile.template"),
-            doc = """The template file to use to generate the Doxyfile. You can provide your own or use the default one.
+            doc = """Template file to use to generate the Doxyfile. You can provide your own or use the default one.
 The following substitutions are available:
 - `# {{INPUT}}`: Subpackage directory in the sandbox.
 - `# {{DOT_PATH}}`: Indicate to doxygen the location of the `dot_executable`
@@ -142,15 +142,15 @@ The following substitutions are available:
             executable = True,
             cfg = "exec",
             allow_single_file = True,
-            doc = "The dot executable to use. Must refer to an executable file.",
+            doc = "dot executable to use. Must refer to an executable file.",
         ),
         "doxygen_extra_args": attr.string_list(default = [], doc = "Extra arguments to pass to the doxygen executable."),
         "_executable": attr.label(
             executable = True,
             cfg = "exec",
             allow_single_file = True,
             default = Label(":executable"),
-            doc = "The doxygen executable to use. Must refer to an executable file.",
+            doc = "doxygen executable to use. Must refer to an executable file.",
         ),
     },
 )
@@ -539,18 +539,22 @@ def doxygen(
     ```
 
     Args:
-        name: A name for the target.
-        srcs: A list of source files to generate documentation for.
-        deps: A list of dependencies whose source, header and data files, and those or the transitive dependencies, will be included in the documentation.
+        name: Name for the target.
+        srcs: List of source files to generate documentation for.
+            Can include any file that Doxygen can parse, as well as targets that return a DefaultInfo provider (usually genrules).
+            Since we are only considering the outputs files and not the sources, these targets **will** be built if necessary.
+        deps: List of dependencies targets whose files present in the 'src', 'hdrs' and 'data' attributes will be collected to generate the documentation.
+            Transitive dependencies are also taken into account.
+            Since we are only considering the source files and not the outputs, these targets **will not** be built.
         dot_executable: Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro
-        configurations: A list of additional configuration parameters to pass to Doxygen.
+        configurations: List of additional configuration parameters to pass to Doxygen.
         doxyfile_template: The template file to use to generate the Doxyfile.
             The following substitutions are available:<br>
             - `# {{INPUT}}`: Subpackage directory in the sandbox.<br>
             - `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.<br>
             - `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute.
         doxygen_extra_args: Extra arguments to pass to the doxygen executable.
-        outs: The output folders bazel will keep. If only the html outputs is of interest, the default value will do.
+        outs: Output folders bazel will keep. If only the html outputs is of interest, the default value will do.
              otherwise, a list of folders to keep is expected (e.g. ["html", "latex"]).
              Note that the rule will also generate an output group for each folder in the outs list having the same name.
 

examples/dependencies/BUILD.bazel

@@ -28,9 +28,24 @@ cc_library(
     deps = [":lib"],
 )
 
+genrule(
+    name = "section",
+    outs = ["Section.md"],
+    cmd = """
+        echo "# Section " > $@
+        echo "This is some amazing documentation with section!!  " >> $@
+        echo "Incredible." >> $@
+    """,
+)
+
 doxygen(
     name = "doxygen",
+    srcs = [
+        "README.md",  # file
+        ":section",  # genrule
+    ],
     project_brief = "Example project for doxygen",
     project_name = "dependencies",
-    deps = [":main"],
+    use_mdfile_as_mainpage = "dependencies/README.md",
+    deps = [":main"],  # cc_library
 )