[Bug 91387] create doxygen docs for the LibreOffice build system from inline comments

https://bugs.documentfoundation.org/show_bug.cgi?id=91387

--- Comment #1 from David H. Gutteridge <dhgutteridge@hotmail.com> ---
Depending upon what your goal is, it's not necessary to create custom tooling
or such. Simply configuring Doxygen to treat Make files as one of the scripting
languages it supports will enable it to parse embedded documentation. Of the
choices, I've found TCL is a better fit than Python, as with the latter,
Doxygen picks up Make variables automatically, but can get some of it kind of
wrong. I infer from looking at the existing documentation samples that the goal
is to document only some of the content (specific targets and variables, not
everything), in which case it's simplest to just manually type out the desired
information at the start of the files. (If on the other hand the goal is
actually to have something automatically parse GNU Make file syntax, it would
probably make more sense to start a side project to add that functionality to
Doxygen itself, rather than maintaining something custom just for LibreOffice.)

I've attached sample Make and configuration files that demonstrate this
approach. They're based upon the existing files in the LibreOffice source. (I
haven't updated the sample's documentation to reflect current reality, just
copied from the old fake C++ file in question, to demonstrate general
feasibility.) This method requires manual application of tags to convey the
desired structure, but still requires less typing than the original approach, I
think.

This is of course the easy part. The more time-consuming effort will be in
actually documenting the Make files! Anyway, my two cents.

-- 
You are receiving this mail because:
You are on the CC list for the bug.