libcrush C API documentation

libcrush C API documentation

[Loic Dachary]

Hi Adam,

I would be great if you could review the libcrush C API documentation merge request at http://libcrush.org/main/libcrush/merge_requests/1/diffs. I deliberately documented part of the external functions because some of them ( crush_make_uniform_bucket for instance ) are support functions for a higher level function ( crush_make_bucket for instance ). If you think a function should be documented and it is not, this is not because it's work in progress, it's because I may have misjudged it.

The unsupported features are undocumented (for instance the tree and straw algorithms). They should probably be compiled out via a #if before the first standalone release of the library binary package. But it did not seem to be a good idea to dive into that while documenting.

You can skip the review of the struct crush_map fields. Nothing was done except changing the existing comments to match Doxygen conventions. There is much to do to improve this. Explaining the tunables is not for the faint of heart.

The format chosen for the documentation is Doxygen, as we discussed. Thanks for suggesting it :-)

Cheers

-- 
Loïc Dachary, Artisan Logiciel Libre

Re: libcrush C API documentation

[Adam C. Emerson]

[-- Attachment #1: Type: text/plain, Size: 1495 bytes --]

On 25/01/2017, Loic Dachary wrote:
> Hi Adam,
> 
> I would be great if you could review the libcrush C API documentation merge request at http://libcrush.org/main/libcrush/merge_requests/1/diffs. I deliberately documented part of the external functions because some of them ( crush_make_uniform_bucket for instance ) are support functions for a higher level function ( crush_make_bucket for instance ). If you think a function should be documented and it is not, this is not because it's work in progress, it's because I may have misjudged it.
> 
> The unsupported features are undocumented (for instance the tree and straw algorithms). They should probably be compiled out via a #if before the first standalone release of the library binary package. But it did not seem to be a good idea to dive into that while documenting.
> 
> You can skip the review of the struct crush_map fields. Nothing was done except changing the existing comments to match Doxygen conventions. There is much to do to improve this. Explaining the tunables is not for the faint of heart.
> 
> The format chosen for the documentation is Doxygen, as we discussed. Thanks for suggesting it :-)
> 
> Cheers

I will be happy to! Do you want me to read for, mostly, technical
coverage etc. or for style and usage and whatnot, too?

-- 
Senior Software Engineer           Red Hat Storage, Ann Arbor, MI, US
IRC: Aemerson@{RedHat, OFTC}
0x80F7544B90EDBFB9 E707 86BA 0C1B 62CC 152C  7C12 80F7 544B 90ED BFB9

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 603 bytes --]

Re: libcrush C API documentation

[Loic Dachary]

On 01/25/2017 07:25 PM, Adam C. Emerson wrote:
> On 25/01/2017, Loic Dachary wrote:
>> Hi Adam,
>>
>> I would be great if you could review the libcrush C API documentation merge request at http://libcrush.org/main/libcrush/merge_requests/1/diffs. I deliberately documented part of the external functions because some of them ( crush_make_uniform_bucket for instance ) are support functions for a higher level function ( crush_make_bucket for instance ). If you think a function should be documented and it is not, this is not because it's work in progress, it's because I may have misjudged it.
>>
>> The unsupported features are undocumented (for instance the tree and straw algorithms). They should probably be compiled out via a #if before the first standalone release of the library binary package. But it did not seem to be a good idea to dive into that while documenting.
>>
>> You can skip the review of the struct crush_map fields. Nothing was done except changing the existing comments to match Doxygen conventions. There is much to do to improve this. Explaining the tunables is not for the faint of heart.
>>
>> The format chosen for the documentation is Doxygen, as we discussed. Thanks for suggesting it :-)
>>
>> Cheers
> 
> I will be happy to! Do you want me to read for, mostly, technical
> coverage etc. or for style and usage and whatnot, too?

As much as you can :-) You can create the HTML pages localy with

git clone http://libcrush.org/main/libcrush.git
cd libcrush
doxygen doc/Doxygen
firefox doc/output/html/index.html

Cheers

-- 
Loïc Dachary, Artisan Logiciel Libre

Re: libcrush C API documentation

[Ming Lin]

On Wed, Jan 25, 2017 at 10:45 AM, Loic Dachary <loic@dachary.org> wrote:
>
> git clone http://libcrush.org/main/libcrush.git
> cd libcrush
> doxygen doc/Doxygen

Nice.

Just FYI, I didn't find "doc" in the default master branch.
It's only in the wip-2-doxygen branch.

> firefox doc/output/html/index.html
>
> Cheers

Re: libcrush C API documentation

[Loic Dachary]

On 01/25/2017 10:36 PM, Ming Lin wrote:
> On Wed, Jan 25, 2017 at 10:45 AM, Loic Dachary <loic@dachary.org> wrote:
>>
>> git clone http://libcrush.org/main/libcrush.git
>> cd libcrush
>> doxygen doc/Doxygen
> 
> Nice.
> 
> Just FYI, I didn't find "doc" in the default master branch.
> It's only in the wip-2-doxygen branch.

Right, thanks for the fix :-)

-- 
Loïc Dachary, Artisan Logiciel Libre