Update functions.md

[RikinR]

added the " Function type " section in the file

Added the Function types section similar to one in Record file .

Fixes #5901

---

• [x] I’ve reviewed the contributor guide and applied the relevant portions to this PR.
• [x] This PR doesn't contain automatically generated corrections or text (Grammarly, LLMs, and similar).
• [x] This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn't use i.e. or e.g., and it avoids I and we (first person).
• [x] This PR uses semantic line breaks of 80 characters or fewer.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Code changes should generally follow the Dart style guide and use dart format.
• Updates to code excerpts indicated by <?code-excerpt need to be updated in their source .dart file as well.

[google-cla[bot]]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[RikinR]

/gcbrun

[atsansone]

/gcbrun

[dart-github-bot]

Visit the preview URL for this PR (updated for commit 81b60c762192585faa0c9b197098a71b0406d04a):

https://dart-dev--pr5944-patch-1-pp3u151g.web.app

[MaryaBelanger]

This looks great, thanks so much @RikinR! I'm going to pull your PR locally to fix the test failure and make some minor additions (I'll leave a comment afterwards explaining what I changed and why, so you can do the same for your future PRs 😄)

[RikinR]

okay, thanks ! @MaryaBelanger

[MaryaBelanger]

/gcbrun

[MaryaBelanger]

@RikinR The test failure was because of the code excerpt failing (happens all the time, no worries).

We have a system where the code blocks we use for examples in markdown files correspond to actual Dart files (in the /examples directory) so that the code is actually tested and kept up to date.

So I added your code example to the functions.dart file, and enclosed it with // #docregion ... // #enddocregion comments. The name of that docregion (function-type) goes in the parenthesis at the end of the <?code-excerpt ... tag in the functions.md file (line 212).

And then, finally, after you do all that, you have to run the command ./dash_site refresh-excerpts (you can read more about that here). That's all, hope that helps with your next contribution!

---

I made a couple other minor changes in this commit too, if you'd like to know why:

• We try to keep lines under 80 characters to make it easier to read/review the markdown, so I broke up your paragraphs into new lines at punctuation marks or where they hit 80.
• You used an html <code> tag inline in one of your paragraphs, but we normally just use backticks (`) to do code font (again, makes the markdown easier to read)
• I moved your entire new section below the function parameters section, because the definition of "function types" is based on parameters so I thought that made more sense.

We're almost done! I'm going to review/edit the actual contents of your PR now, and then we'll get this merged 🤞 Thanks again!

[mmcdon20]

I'm confused by the following:

In Dart, function types can be explicitly declared based on context.

What does this mean? What context?

Here is an example of declaring function types:

int add(int a, int b) => a + b;
// int function(int, int) = add;

But the above example doesn't declare a function type. There is a function declaration, and a comment, but no function type declaration. The comment sort of looks like a function type declaration but the syntax is wrong. The type of int add(int a, int b) => a + b; is int Function(int, int) (note the capital F in Function). This means you can assign add to a variable of type int Function(int, int), ie int Function(int, int) myVariable = add;, or you can pass add to a function or method that accepts an int Function(int, int) as an argument, ie [1, 2, 3, 4, 5].reduce(add), etc.

When you declare functions, you can specify the type of function,

You declare a function type when you want to store a function in a variable, accept a function as an argument to a function, return a function from a function, ie the same places you would declare any other type such as int, or String etc.

which indicates that the return value from the function should be of that specific type.

The return type is part of it, but a function type declaration describes the entire signature of a function, which in dart can include:

• The return type
• The types for each of the positional parameters
• The types and names of each named parameter (and if they are required)
• Any generic type arguments and their restrictions

To give a more complex example, which illustrates the above, the following function definition:

T lookupAtN<T extends Object>(List<T> elements, {required int n}) => elements[n];

Has the following type

T Function<T extends Object>(List<T>, {required int n})

Therefore I can define a variable of the above type and assign lookupAtN to the variable.

T Function<T extends Object>(List<T>, {required int n}) myVariable = lookupAtN;

---

Also it might be worth linking to this from built-in types page, as I mentioned in the original issue.

[RikinR]

@mmcdon20 . Thanks for correcting . I do get your your point , you were talking about "Function Type" declaration for a variable and what I did was declared a function . So should I mention this "Function Type" directly to built-in-types-page ?

[eernstg]

Drive-by comment: The section about 'Function types' might be a better fit right after the section 'Functions as first-class objects': First-class function objects can be assigned to variables and passed as actual arguments to function invocations, and it makes sense for those variables and parameters to have a declared type which is a function type. If we don't have first-class function objects then we would never be able to use a function type because there are no values that said type could be the type of.

(OK, we could still write void Function()? x = null;, but there would be no non-silly way to use a function type ;-)

We could then have something along these lines:

Function types

We can specify the type of a function, which is known as a function type. It is actually the type of a first-class function object: An expression whose type is a function type can only evaluate to a first-class function object. A function type is obtained from a function declaration header by replacing the function name by the word Function. Moreover, we are allowed to omit the names of positional parameters, but the names of named parameters cannot be omitted. For example:

void printElement(int element) => print(element);

void doPrint(void Function(int) printFunction, {required List<int> list}) {
  list.forEach(printFunction);
}

var list = [1, 2, 3];

// Store `doPrint` in a variable and call it.
void Function(void Function(int), {required List<int> list}) g = doPrint;
g(printElement, list: list);

[mmcdon20]

So should I mention this "Function Type" directly to built-in-types-page ?

I think just a link in the bulleted list should be enough here. Same thing is done for Records.

[sfshaza2]

/gcbrun

[sfshaza2]

@eernstg, Marya is out on leave. Can I approve and land this PR?

[mmcdon20]

@sfshaza2 The PR hasn't been updated to account for the feedback. I think the following changes should be made:

1. The explanation of function types should be closer to what @eernstg wrote (I would be fine with Erik's explanation as is).
2. The 'Function types' section should be moved to after the 'Functions as first-class objects' section.
3. Add a link to function types in the bulleted list at the top of built in types page just like it is for record types.

[redbrogdon]

Hey, @RikinR, it looks like you haven't had time to get back to this PR in a while. Could you let us know (ideally in the next day or so) if you're still planning to do so? Otherwise we can move forward with #6037.

[RikinR]

hey sorry ! actually I am moving abroad this month thus I will not be able to work on this issue. Sorry for the inconvenience . hope you understand

[redbrogdon]

hey sorry ! actually I am moving abroad this month thus I will not be able to work on this issue. Sorry for the inconvenience . hope you understand

Life happens. I'll close the PR. In the meantime, I hope you enjoy your new home!