Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document user-defined literals #206

Merged
merged 1 commit into from
Oct 11, 2015
Merged

Document user-defined literals #206

merged 1 commit into from
Oct 11, 2015

Conversation

dean0x7d
Copy link
Contributor

I noticed that named arguments were not covered on the "Overview" page so I added that before the literals. There's also a little bit extra about variadic templates in the "Portability" section.

The new text which describes the UDL functionality is all on the "Overview" page. I'm not really sure what, if anything, should be added to the "API" page. The actual signature of the literal operators

ImplDetail operator"" _udl(const char *s, std::size_t)

is not really useful for the end user. The return type is an implementation detail and the parameter list only matters to the compiler. The final syntax is pretty easy to understand

"format_str"_format(args...)
"arg_name"_a=value

but it doesn't correspond to the literal operator signature.

So I see three options here:

  1. Regular doxygen docs with the operator"" signature.
  2. Custom write the docs with final syntax as the signature.
  3. Add a note inside the existing API docs for fmt::format and fmt::arg mentioning _format and _a as alternative syntax.

Let me know which of those, if any, would be preferable.

vitaut added a commit that referenced this pull request Oct 11, 2015
Document user-defined literals
@vitaut vitaut merged commit dd60ec6 into fmtlib:master Oct 11, 2015
@vitaut
Copy link
Contributor

vitaut commented Oct 11, 2015

Looks great, thanks!

I agree that the signatures of literal operators are not particularly useful for the users, but it might be a good idea to document them anyway in the API section at least for the sake of introducing the names _format and _a that reside in a separate namespace fmt::literal and give a location to link to. As in other cases, the API docs could give examples of use which would help users less familiar withe UDL. It would probably be a good idea to keep the API docs of _format and _a close to that of format and arg respectively.

@dean0x7d dean0x7d deleted the udl-docs branch October 11, 2015 20:54
@dean0x7d
Copy link
Contributor Author

I ran into a bit of trouble. It looks like Sphinx can't parse user-definel literals:

cppformat/doc/api.rst:29: WARNING: Error when parsing function declaration:
If no return type {
Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 26]
  internal::UdlFormat<char> fmt::literals::operator""_format(const char *, std::size_t)
  --------------------------^
} else if return type {
Invalid definition: Expected identifier in nested name. [error at 49]
  internal::UdlFormat<char> fmt::literals::operator""_format(const char *, std::size_t)
  -------------------------------------------------^
}

That's after running make doc with this setup: c12e3d6.
I took a look at the Sphinx C++ parser and it wouldn't be too difficult to add UDL support. I'll see about submitting a PR to Sphinx. But it would take time for the changes to trickle down to a stable version.

@dean0x7d dean0x7d restored the udl-docs branch October 11, 2015 21:15
@dean0x7d dean0x7d deleted the udl-docs branch October 12, 2015 22:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants