Documentation for load, loadsync does not correspond with implementation and examples

[Crazy-Duck]

protobuf.js version: 6.3.1

Going by the API doc, the only load functions available are Root.load and Root.loadSync, who take filename, options and callback as arguments, with options being a ParseOptions object (permitting for example to specify you don't want camelCase conversion). Going by the example and these docs, I expected to be able to do the following:

var Protobuf = require('protobufjs'),
    fs = require("fs");


var folder = fs.readdirSync(__dirname + '/proto'); // folder containing proto files
var schema = Protobuf.loadSync(folder.map(filename => __dirname + '/proto/' + filename), {keepCase: true}); // Produces error

However, when passing an options object, a stacktrace is generated implying that the options object is taken as a Root object on which load is invoked...

Stack trace:

/home/ubuntu/workspace/node_modules/protobufjs/src/index.js:64
    return root.loadSync(filename);
                ^

TypeError: root.loadSync is not a function
    at Object.loadSync (/home/ubuntu/workspace/node_modules/protobufjs/src/index.js:64:17)
    at Object.<anonymous> (/home/ubuntu/workspace/poc_proto.js:6:23)
    at Module._compile (module.js:571:32)

When going through the source, I saw that index.js exports itself undocumented load and loadSync functions, who take a different set of parameters, namely filename, root and callback. These functions check if a root parameter is present and if so invoke load/loadSync on this object, with the given filename and callback as arguments. If no root argument is given, a new Root object is generated and load/loadSync are called on this new object. This leads to the terribly confusing situation where, if you don't want to specify options, you can just follow the example using the exported functions, however, when you want to specify options, you need to first create a Root object yourself and use this object instead (thus effectively re-implementing the exported load/loadSync functions, but this time taking into account the options.

Is this intended behavior of the library? If so, it might be necessary to perhaps modify the docs to make this distinction clear..

[dcodeIO]

When first implemented, keepCase was meant for pbjs' not recommended --keep-case option. That's why I left it out in the convenience API.

When I think about it, now that IE8 support has been dropped and alternative getter/setter functions are a thing of the past, it's actually not necessary anymore to mark this as not recommended. Will take a look!

[dcodeIO]

You can now set the keepCase option globally:

protobuf.parse.defaults.keepCase = true;

This affects all load/loadSync functions where/when no ParseOptions are specified. These fall back to use protobuf.parse.defaults.

Note that protobuf.load/loadSync are convenience functions, so I'd like to keep them rather simple.

[dcodeIO]

Changed this to fall back to protobuf.parse.defaults - edited the previous comment accordingly. Also added additional links to the documentation so that this is easier to discover.

[Crazy-Duck]

Alright, thanks a lot for the fast response!

[dcodeIO]

Closing this for now as 6.4.0, which is now released, should solve the issue. Feel free to reopen the issue if necessary.