lix-project/lix

Fork 54

Developer Docs Should have Function -> Header Mapping #931

New issue

Open

opened 2025-07-26 08:39:31 +00:00 by blitz · 5 comments

blitz commented

2025-07-26 08:39:31 +00:00

Problem

When trying to develop against the C++ API, the only way to find out what header I should include is by grepping through the libraries' headers or guessing from other projects using the API (nix-eval-jobs).

Proposal

For each type/function, the Doxygen developer docs should list which header defines it. A good example is the C++ reference: https://en.cppreference.com/w/cpp/algorithm/for_each.html

Some other ideas to consider:

a high-level description of what each of the libraries scope is to give a bit of a mental model of what is in which library
a version of the developer docs published on the web

Checklist

checked latest Lix manual or its source code
checked documentation issues and recent documentation changes for possible duplicates

## Problem When trying to develop against the C++ API, the only way to find out what header I should include is by grepping through the libraries' headers or guessing from other projects using the API (nix-eval-jobs). ## Proposal For each type/function, the Doxygen developer docs should list which header defines it. A good example is the C++ reference: https://en.cppreference.com/w/cpp/algorithm/for_each.html Some other ideas to consider: - a high-level description of what each of the libraries scope is to give a bit of a mental model of what is in which library - a version of the developer docs published on the web - ## Checklist  - [x] checked [latest Lix manual] or its [source code] - [x] checked [documentation issues] and [recent documentation changes] for possible duplicates [latest Lix manual]: https://docs.lix.systems/manual/lix/nightly [source code]: https://git.lix.systems/lix-project/lix/src/main/doc/manual/src [documentation issues]: https://git.lix.systems/lix-project/lix/issues?labels=151&state=all [recent documentation changes]: https://gerrit.lix.systems/q/p:lix+path:%22%5Edoc/manual/.*%22

blitz added the

docs

label

2025-07-26 08:39:31 +00:00

jade commented

2025-07-26 17:15:52 +00:00

Owner

FYI that API is highly unstable and you can use it at your own peril of dealing with the changes; the most effective way is to develop against lix HEAD.

As for the other ideas, I think there might be some bugs for those already but they're unlikely to happen without some help from others.

However, are you suggesting there's a wrong doxygen config setting we can fix to actually show the header names? I'm missing some exact context of what's wrong because I think most of our team doesn't use these at all and just reads the headers directly.

FYI that API is highly unstable and you can use it at your own peril of dealing with the changes; the most effective way is to develop against lix HEAD. As for the other ideas, I think there might be some bugs for those already but they're unlikely to happen without some help from others. However, are you suggesting there's a wrong doxygen config setting we can fix to actually show the header names? I'm missing some exact context of what's wrong because I think most of our team doesn't use these at all and just reads the headers directly.

jade added the

devx

label

2025-07-26 17:17:21 +00:00

raito commented

2025-07-26 18:53:40 +00:00

Owner

@jade yep, the idea is to show which header to include to get access to certain items. I think this is a Doxygen config problem or maybe a Doxygen limitation, we need to look into it.

blitz commented

2025-07-26 21:16:05 +00:00

Author

Yes, if there is a setting that shows which header defines a class/function that would be really helpful!

pennae commented

2025-07-26 21:18:31 +00:00

Owner

we could just enable that setting. if you know how to do it, CLs are always welcome!

jade commented

2025-07-27 02:30:57 +00:00

Owner

@blitz wrote in #931 (comment):

Yes, if there is a setting that shows which header defines a class/function that would be really helpful!

Most likely we'll not go looking for one in the medium term as we don't use the doxygen much but if it's important to you please feel free to look at the doxygen docs; you probably know as much or more than us about how it works and we'll gladly take a patch to simply fix the setting.

@blitz wrote in https://git.lix.systems/lix-project/lix/issues/931#issuecomment-13601: > Yes, if there is a setting that shows which header defines a class/function that would be really helpful! Most likely we'll not go looking for one in the medium term as we don't use the doxygen much but if it's important to you please feel free to look at the doxygen docs; you probably know as much or more than us about how it works and we'll gladly take a patch to simply fix the setting.