# Build system inline documentation

**URL:** <https://forum.openwrt.org/t/build-system-inline-documentation/213921>\
**Category:** Talk about Documentation\
**Created:** [October 25, 2024, 10:50am UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921 "2024-10-25T10:50:24Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![matsievskiysv](https://forum.openwrt.org/letter_avatar/matsievskiysv/32/5_5575768a8748004e209b776fc1b2916d.png) [@matsievskiysv](https://forum.openwrt.org/u/matsievskiysv)\
**Post date:** [October 25, 2024, 10:50am UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/1 "2024-10-25T10:50:24Z")

</div>

Hello!

I'm studying the OpenWRT build system to add a new target. While at it, I could add Doxygen like comments to the makefiles.  
If such a contribution is welcome, what should be the preferred documentation syntax?

---

<div class="post-metadata">

**Author:** ![matsievskiysv](https://forum.openwrt.org/letter_avatar/matsievskiysv/32/5_5575768a8748004e209b776fc1b2916d.png) [@matsievskiysv](https://forum.openwrt.org/u/matsievskiysv)\
**Post date:** [October 25, 2024, 12:28pm UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/2 "2024-10-25T12:28:59Z")

</div>

Maybe something like

```make
##@
# @brief Call function for each group of arguments.
#
# @param 1: List of lists of arguments. Lists are separated by `|`.
# @param 2: Function to call for list of arguments.
##
define split_args
$(foreach data, \
	$(subst |,$(space),\
		$(subst $(space),^,$(1))), \
	$(call $(2),$(strip $(subst ^,$(space),$(data)))))
endef

```

---

<div class="post-metadata">

**Author:** ![miminashi](https://forum.openwrt.org/user_avatar/forum.openwrt.org/miminashi/32/88750_2.png) [@miminashi](https://forum.openwrt.org/u/miminashi)\
**Post date:** [October 27, 2024, 11:56am UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/3 "2024-10-27T11:56:04Z")

</div>

I also think this is a good idea.  
It took me a whole week to understand the Makefile for OpenWrt...

---

<div class="post-metadata">

**Author:** ![m95d](https://forum.openwrt.org/user_avatar/forum.openwrt.org/m95d/32/30883_2.png) [@m95d](https://forum.openwrt.org/u/m95d)\
**Post date:** [November 9, 2024, 5:41pm UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/4 "2024-11-09T17:41:29Z")

</div>

To those of you who understand the build system, could you please write a guide for everyone else interested? Thanks!

Brief comments in code don't paint the big picture.

---

<div class="post-metadata">

**Author:** ![matsievskiysv](https://forum.openwrt.org/letter_avatar/matsievskiysv/32/5_5575768a8748004e209b776fc1b2916d.png) [@matsievskiysv](https://forum.openwrt.org/u/matsievskiysv)\
**Post date:** [November 13, 2024, 4:21am UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/5 "2024-11-13T04:21:39Z")

</div>

> Brief comments in code don't paint the big picture.

True, but it's better than nothing:)

The testing commit [https://github.com/openwrt/openwrt/pull/16888](https://github.com/openwrt/openwrt/pull/16888) got merged; the Doxygen like syntax from the message above may be used for documentation. If anyone would like to participate in this task, patches are welcome.

---

<div class="post-metadata">

**Author:** ![miminashi](https://forum.openwrt.org/user_avatar/forum.openwrt.org/miminashi/32/88750_2.png) [@miminashi](https://forum.openwrt.org/u/miminashi)\
**Post date:** [November 13, 2024, 10:56am UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/6 "2024-11-13T10:56:57Z")

</div>

How can I generate documentation from these .mk files using doxygen?

---

<div class="post-metadata">

**Author:** ![matsievskiysv](https://forum.openwrt.org/letter_avatar/matsievskiysv/32/5_5575768a8748004e209b776fc1b2916d.png) [@matsievskiysv](https://forum.openwrt.org/u/matsievskiysv)\
**Post date:** [November 15, 2024, 6:08pm UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/7 "2024-11-15T18:08:36Z")

</div>

AFAIK, there're no make documentation generators available.

---

<div class="post-metadata">

**Author:** ![matsievskiysv](https://forum.openwrt.org/letter_avatar/matsievskiysv/32/5_5575768a8748004e209b776fc1b2916d.png) [@matsievskiysv](https://forum.openwrt.org/u/matsievskiysv)\
**Post date:** [November 30, 2024, 2:31pm UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/8 "2024-11-30T14:31:54Z")

</div>

I'm slowly adding more comments. The progress may be tracked at [github](https://github.com/matsievskiysv/openwrt/tree/doc) (branch is subject to squashing and force pushes).

---

<div class="post-metadata">

**Author:** ![antonk](https://forum.openwrt.org/user_avatar/forum.openwrt.org/antonk/32/93698_2.png) [@antonk](https://forum.openwrt.org/u/antonk)\
**Post date:** [December 7, 2024, 2:30am UTC](https://forum.openwrt.org/t/build-system-inline-documentation/213921/9 "2024-12-07T02:30:08Z")

</div>

> [@miminashi](#):
>
> How can I generate documentation from these .mk files using doxygen?

I suppose a sed or awk script could extract these comments, compile something useful out of them and print them out. Not a bad idea IMO.

Also, great job @matsievskiysv 👏