search

dbbs-lab / bsb-core

The Brain Scaffold Builder
https://bsb.readthedocs.io
GNU General Public License v3.0
21 stars 16 forks source link

Document the storage interfaces from the user perspective #695

Open francesshei opened 1 year ago

francesshei commented 1 year ago

The label method docstring currently reads: 

        Should label the cells with given labels.

        :param cells: Array of cells in this set to label.
        :type cells: numpy.ndarray
        :param labels: List of labels
        :type labels: list[str]

Could be useful to explicitly state that the function assigns each label in the list to each cell.

Helveg commented 1 year ago

This docstring is for the interface of PlacementSet, aimed at developers trying to implement their own PlacementSet for a new storage engine. In that case, they should know that this function should label the cells with given labels.

That said, encountering this docstring in the BSB docs as a user is quite confusing. Instead of linking to the bsb.storage.interfaces.PlacementSet, we should link to bsb_hdf5.PlacementSet as the de facto default implementation.