github.com/sberex/go-sberex@v1.8.2-0.20181113200658-ed96ac38f7d7/mobile/doc.go (about)

     1  // This file is part of the go-sberex library. The go-sberex library is 
     2  // free software: you can redistribute it and/or modify it under the terms 
     3  // of the GNU Lesser General Public License as published by the Free 
     4  // Software Foundation, either version 3 of the License, or (at your option)
     5  // any later version.
     6  //
     7  // The go-sberex library is distributed in the hope that it will be useful, 
     8  // but WITHOUT ANY WARRANTY; without even the implied warranty of
     9  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser 
    10  // General Public License <http://www.gnu.org/licenses/> for more details.
    11  
    12  // Package geth contains the simplified mobile APIs to go-sberex.
    13  //
    14  // The scope of this package is *not* to allow writing a custom Sberex client
    15  // with pieces plucked from go-sberex, rather to allow writing native dapps on
    16  // mobile platforms. Keep this in mind when using or extending this package!
    17  //
    18  // API limitations
    19  //
    20  // Since gomobile cannot bridge arbitrary types between Go and Android/iOS, the
    21  // exposed APIs need to be manually wrapped into simplified types, with custom
    22  // constructors and getters/setters to ensure that they can be meaninfully used
    23  // from Java/ObjC too.
    24  //
    25  // With this in mind, please try to limit the scope of this package and only add
    26  // essentials without which mobile support cannot work, especially since manually
    27  // syncing the code will be unwieldy otherwise. In the long term we might consider
    28  // writing custom library generators, but those are out of scope now.
    29  //
    30  // Content wise each file in this package corresponds to an entire Go package
    31  // from the go-sberex repository. Please adhere to this scoping to prevent this
    32  // package getting unmaintainable.
    33  //
    34  // Wrapping guidelines:
    35  //
    36  // Every type that is to be exposed should be wrapped into its own plain struct,
    37  // which internally contains a single field: the original go-sberex version.
    38  // This is needed because gomobile cannot expose named types for now.
    39  //
    40  // Whenever a method argument or a return type is a custom struct, the pointer
    41  // variant should always be used as value types crossing over between language
    42  // boundaries might have strange behaviors.
    43  //
    44  // Slices of types should be converted into a single multiplicative type wrapping
    45  // a go slice with the methods `Size`, `Get` and `Set`. Further slice operations
    46  // should not be provided to limit the remote code complexity. Arrays should be
    47  // avoided as much as possible since they complicate bounds checking.
    48  //
    49  // If a method has multiple return values (e.g. some return + an error), those
    50  // are generated as output arguments in ObjC. To avoid weird generated names like
    51  // ret_0 for them, please always assign names to output variables if tuples.
    52  //
    53  // Note, a panic *cannot* cross over language boundaries, instead will result in
    54  // an undebuggable SEGFAULT in the process. For error handling only ever use error
    55  // returns, which may be the only or the second return.
    56  package geth