* libcrush C API documentation
@ 2017-01-25 18:23 Loic Dachary
2017-01-25 18:25 ` Adam C. Emerson
0 siblings, 1 reply; 5+ messages in thread
From: Loic Dachary @ 2017-01-25 18:23 UTC (permalink / raw)
To: Adam C. Emerson; +Cc: Ceph Development
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: libcrush C API documentation
2017-01-25 18:23 libcrush C API documentation Loic Dachary
@ 2017-01-25 18:25 ` Adam C. Emerson
2017-01-25 18:45 ` Loic Dachary
0 siblings, 1 reply; 5+ messages in thread
From: Adam C. Emerson @ 2017-01-25 18:25 UTC (permalink / raw)
To: Loic Dachary; +Cc: Ceph Development
[-- 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 --]
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: libcrush C API documentation
2017-01-25 18:25 ` Adam C. Emerson
@ 2017-01-25 18:45 ` Loic Dachary
2017-01-25 21:36 ` Ming Lin
0 siblings, 1 reply; 5+ messages in thread
From: Loic Dachary @ 2017-01-25 18:45 UTC (permalink / raw)
To: Adam C. Emerson; +Cc: Ceph Development
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
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2017-01-25 22:26 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-01-25 18:23 libcrush C API documentation Loic Dachary
2017-01-25 18:25 ` Adam C. Emerson
2017-01-25 18:45 ` Loic Dachary
2017-01-25 21:36 ` Ming Lin
2017-01-25 22:26 ` Loic Dachary
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.