Documentation in wiki

[jfalcou]

[odinthenerd]

I guess this is a good place to ask for documentation ;)

if I have a metafunction lets say:

template<typename T, typename U>
struct MyData{};

template<typename T>
struct GetU;
template<typename T, typename U>
struct GetU<MyData<T,U>> {
    using type = U;
}

and I want to pass it to transform as a lambda what do I need to wrap it with in order to pass it as a lambda?

using l = list<MyData<int,int>,MyData<char,bool>>;
using restult = transform<l,WhatWrapperDoIUse<GetU>>;

Surely there is a wrapper class like:

template<template<typename...> class T>
struct Template{
    template<typename... Ts>
    using apply = T<Ts...>;
};

but I can't seem to find it.

[jfalcou]

passing GetU<_1> should be enough as in MPL.

[odinthenerd]

Thanks for the answer, that works well, brigand::quote also does what I wanted.

[jfalcou]

@ccharly, don't forget to make th python thingy for this issue ;)

[edouarda]

I started the layout and wrote the first tutorial. I think the best is to do a little every day rather than everything in one pass. We should discuss how to describe the functions because a lot can be scripted I think.

[jfalcou]

I guess @ccharly script was used ?

As for the function, I think we should have a standardese like wording.

[edouarda]

I used his script but had to do a pass after there is a bug that writes \ instead of / in the path.

I'm not sure I understand your comment about the functions? My question was about, how much can we generate by a script and avoid the mistake of typing by hand? We could use doxygen but I submit it might suffer with the TMP heavy code.

[edouarda]

Do you guys have any ideas for tutorials?

[edouarda]

We could also use github pages.

[nilsdeppe]

I'd like to start adding documentation as I use brigand, partly just to remind myself how to use things in the future and partly because that's probably not a bad way to go about doing it. Has there been any further thought on how to implement documentation? Newer doxygen handles template parameters, as well as template-template parameters and variadic templates. Some decision on how to document the corresponding lazy evaluations would need to be made too. Maybe these should be described in the non-lazy documentation as well? Louis Dionne is using Doxygen with Boost.hana and it seems to work out, we could ask to get some feedback from him. Thoughts?

[ldionne]

FWIW, I hate Doxygen with all my heart but I was not aware of a better solution at the time of writing Hana's documentation. It's full of quirks and I can't really recommend it for documenting template-heavy libraries. If you do end up using Doxygen, you should however consider taking inspiration from what I've done. I've spent (lost?) many many hours trying to get something decent out of Doxygen, so hopefully this can be useful to you too.

[brunocodutra]

I can only but but echo Louis.

I too decided to document my TMP library using Doxygen, because I didn't know better at the time.

It worked out better than I expected in the end, but not without many many days lost on heavy tweaking of undocumented features.

http://brunocodutra.github.io/metal/

If you really decide to go down this path, which is probably not a good idea, do contact me, it wouldn't be too hard to extract the hacks I've written in javascript/CSS to patch Doxygen as a drop in reusable module.

https://github.com/brunocodutra/metal/blob/master/doc/js/metal.js

That said, I'm not aware of an alternative for documenting TMP libraries. Maybe Boost.Doc, but I don't know.

[edouarda]

In quasardb we use Doxygen to describe ou C-API and that's a use case where it works nicely. For TMP honestly I think it may be easier and quicker to write a Python script. I'm open to suggestions.

[mkurdej]

I may just suggest trying out standardese (https://github.com/foonathan/standardese). It's more or less Doxygen-like, but thought throughout for modern C++ (including TMP). I've tried it on toy projects only, nothing of real-world size, but it seems like a nice way to explore.

[odinthenerd]

I'm all for @foonathan 's standardese!

[foonathan]

I've put the output standardese currently generates on my website. You can browse it by file: http://foonathan.net/doc/brigand/standardese_files.html Or by entity: http://foonathan.net/doc/brigand/standardese_entities.html As there are no documentation comments it just generates a synopsis of the file. I

The option to generate the documentation were: standardese -I/tmp/brigand /tmp/brigand/brigand/ --input.blacklist_namespace=detail --compilation.comments_in_macro=false --output.format=html The compilation option was needed because of some Boost.MPL stuff, would be an error otherwise. When you play with it yourself, please build the develop branch as I had to fix a couple of issues there.

[edouarda]

Roger that, thanks!

[odinthenerd]

thanks @foonathan!

Just noticed in the case of std::integral_constant<std::size_t, sizeof...(T)> you are linking to a search for std::integral_constant<std::size_t, sizeof...(T)> which finds nothing, searching for std::integral_constant would probably yield better results (minor low priority feature request ;)

[foonathan]

I've fixed that on develop.

If there is anything else I can improve or if you need help with anything, let me know.

[nilsdeppe]

@foonathan this is great! Thanks for helping out so quickly.

I'll start adding documentation as I work with brigand. Deciding on how to document everything might be best done once we see what things look like and have done some experimentation.

[foonathan]

I've updated the generated documentation with the latest develop build as well as enabled the option --output.require_comment_for_full_synopsis=false. It forces the full synopsis of class types in the file synopsis as welll; it was just to show how each synopsis will look before the documentation is written.

[edouarda]

That's pretty awesome, thanks!