Is it possible to show the documentation of a function in the documentation of another function residing in a different file? Macros are only valid in their own file.
In the Flutter source code, they use something like this, but it does not seem to have any effect:
/// {#macro flutter.widgets.editableText.keyboardType}
Macro docs is what you are looking for. They are already explained here but in summary allows you do exactly what you want: copy a documentation from a place to somewhere else without re-write.
The best you can do is link to the referenced function.
file_a.dart
/// Also see [functionB].
void functionA() {}
file_b.dart
/// Another function.
void functionB() {}
https://dart.dev/guides/language/language-tour#documentation-comments
Related
With dart it is possible to prefix class/function definition by a commentary so that the analyzer will interpret it as documentation:
/// Some documentation for [Foo]
class Foo {
}
But how can I achieve the same behavior, with parameters instead?
I tried the following:
void myFunction(
/// Some parameter documentation
String parameter,
) {
}
But this doesn't work.
However, it seems possible because dartanalyzer do contain a property on ParameterElement for documentation.
https://www.dartlang.org/guides/language/effective-dart/documentation
Here's the offical Dart language guidelines for documentation best practice. It covers most/all cases and has great examples of do's and don't's.
This bit shows the way to include parameters. Basically, wrap the parameters in square brackets and within a sentence explaining it.
I need to reach my string.xml files from code in a Xamarin.Android project. So, basically I need to use the getString() method of Resources (as I have searched this very site), but there isn't any! Only GetObject<T> is here.
I'm going after it here:
Android.Content.Res.Resources.getString(...).
According to the docs, there is a String GetString (Int32 id) function. You need to get a Resources instance from the application context, using getResources(), then you can call the method.
This is more of a coding style question but i believe it is valid. Coming from an obj c background i always create a .h and a .m when creating a class. However with swift that changes and all that goes into a single file. I know that for some people this is cool but i miss having these two things separate.
Quoting a comment from Zaph
"What I miss is a list of public methods as opposed to searching an
entire source file for methods not marked private. There is a
programming concept of "writing to the interface". And the public
methods should be carefully picked, not just because the developer
forgot to make some private."
is there a way to have a header - implementation class in separate files using swift? Maybe some trick?
Thanks
May be you can use Generated Interface to view all the public methods and properties. You can find that option at the bottom of related files popup in the upper-left of the source editor window. To switch back, click Original Source in the same pop up.
Shortcut: control + cmd + down arrow
This is how generated interface file looks.
As far as i'm aware, this cannot be done. That being said, if set out your .swift files correctly then they are still very readable. I tend to follow this as a guideline for styling in swift and i find that it breaks things up into readable sections, especially by using // MARK: as well.
In short, no.. But what do you miss..? Once you get used to it, you will probably prefer it like this! The old separation has no clear advantage over this new one!
More and more languages use this approach, as it reduce coupling and errors.
So when you change the signature of a function, to need to check another file to update it, it's only duplication without any added value.
The problem you describe (how to see only "public" functions) is usually done buy tools( IDE) or documentation generators.
You can create 2 swift files:
YourClassNameHeader.swift
class YourClassName {// put here all your properties
}
YourClassNameMethods.swift or YourClassNamePrivate.swift
extension YourClassName { // put here all private methods and
properties }
But in general its not good practise
I'm trying to used a method called _dounderlinew(). I'm studying the other method that was list down on the documentation of TCPDF, and it was says that this method's access is PROTECTED. This is the reason why I can't make it work just like the others. Hmm Can anyone explain me why I'm getting errors like this and how can I used this method? THANKS.
Codes I USeds
$pdf->_dounderlinew(x, y, '');
_dounderlinew() is protected because it is used in the TCPDF class to output the actual PDF code, based on your input, so it is of no use to you. As the PHP manual says:
Members declared protected can be accessed only within the class
itself and by inherited and parent classes.
By using it I assume you wish to underline text (maybe inside a cell), for that you can use the SetFont function and set the style parameter to 'U':
SetFont($family, $style='U', $size=null, $fontfile='', $subset='default', $out=true)
And the other parameters as you wish of course.
In declaration of class "DeclarationMirror" I found these documentation about the "owner" property.
For a `parameter`, `local variable` or `local function` the owner is
the immediately enclosing function.
I cannot understand how interpret this information because I cannot find documentation about how to reflect the following declarations through Dart mirrors library.
Local variable
Local function
How should I interpret these terms applied to practical usage of this library?
Notice about the declarations that must be necessarily implemented in future but, for several reasons, currently not implemented.
Information unreliable and can not be perceived as documentation.
I more interested in item #1.
If this is a real documentation but not a unreliable information then where I can find information on which based these documentation?
That is, where is information about described in documentation local variables and local functions mirrored declarations?
I am about how to reflect them from their owners.
I hope that I quite correctly asked question about the official documentation, given its purpose.
If there exist another way to describe this I'll be glad to hear it.
P.S.
This question asked on that reason that there is no other available information found in official documentation.
P.S.
Sample of code:
var clazz = reflectClass(MyClass);
var method = clazz.declarations[#myMethod];
// How to reflect mentioned in documentation local variable?
var localVariable = method.declarations[#myLocalVariable];
The sample of code is just an example, but official documentation is more similar to the law. It must clearly be interpreted.
As I see this:
The immediately enclosing function is indeed the owner of the local variables and local functions.
But that doesn't include that you can get hold of them by reflection.
I tried to assign a local function to a field of the class and tried then to get hold of the function using reflection. I got the field but don't know how to get the value the field references to (the local func)
Maybe this is possible but I couldn't find how.
If this would work the owner would probably be the enclosing function.
AFAIR there was a discussion somewhere that it is currently not possible to access local members using reflection but I'm not very sure about this.
I also think I saw somewhere that you can get the source of a function as text if that is of any use...