Clarify dep type yielded by element.dependencies

[harrysarson]

Update the note in the docs for element.dependencies to clarify that sometimes this function returns runtime dependencies (and explain when this happens).

[gtristan]

I don't like splitting hairs in this documentation, as it is a bit redundant.

The issue is what is considered "build dependencies" for an element.

Rather, it may be good to provide a link in this docstring to https://docs.buildstream.build/master/format_declaring.html#dependency-types

See the note where we clarify this (which is a much more satisfying explanation IMO):

It is assumed that a dependency which is required for building an element must run while building the depending element. This means that build depending on a given element implies that that element’s runtime dependencies will also be staged for the purpose of building.

Perhaps we can reword your patch in a way that links to this section and clarifies that the dependencies are build dependencies in the context of a toplevel element which invoked this function ?

[harrysarson]

Yes, I can have a go at redrafting this. I think the thing that caused me confusion when I read this documentation is that the context which determines whether this function returns buildtime or runtime dependencies is whether the element you call the dependency function on is the toplevel element or one of its dependencies.