Still book keeping should be done in a single place. It’s confusing if TODO/missing feature lists are spread over doxygen comments, bugzilla bug reports, cards, … I’d use doxygen only for documenting the existing code, and keep list missing features somewhere else.
E.g. in this case, when someone adds the missing function (eventually), it’s easy to forget to remove the comment from the reserve function (or N other places) -Petri From: ext Bill Fischofer [mailto:[email protected]] Sent: Friday, August 29, 2014 3:19 PM To: Mike Holmes Cc: Savolainen, Petri (NSN - FI/Espoo); [email protected] Subject: Re: [lng-odp] [PATCH] odp_shared_memory.h: Document odp_shm_reserve We definitely need the closure APIs to be part of v1.0 for completeness. For now noting their absence as bugs is a good way of reminding us of that fact. Bill On Fri, Aug 29, 2014 at 6:34 AM, Mike Holmes <[email protected]<mailto:[email protected]>> wrote: On 29 August 2014 04:05, Savolainen, Petri (NSN - FI/Espoo) <[email protected]<mailto:[email protected]>> wrote: > -----Original Message----- > From: > [email protected]<mailto:[email protected]> > [mailto:lng-odp-<mailto:lng-odp-> > [email protected]<mailto:[email protected]>] On Behalf Of ext > Mike Holmes > Sent: Thursday, August 28, 2014 11:54 PM > To: [email protected]<mailto:[email protected]> > Subject: [lng-odp] [PATCH] odp_shared_memory.h: Document odp_shm_reserve > > Signed-off-by: Mike Holmes > <[email protected]<mailto:[email protected]>> > --- > platform/linux-generic/include/api/odp_shared_memory.h | 5 ++++- > 1 file changed, 4 insertions(+), 1 deletion(-) > > diff --git a/platform/linux-generic/include/api/odp_shared_memory.h > b/platform/linux-generic/include/api/odp_shared_memory.h > index 8ac8847..d75b179 100644 > --- a/platform/linux-generic/include/api/odp_shared_memory.h > +++ b/platform/linux-generic/include/api/odp_shared_memory.h > @@ -21,7 +21,7 @@ extern "C" { > > #include <odp_std_types.h> > > -/** Maximum shared memory block name lenght in chars */ > +/** Maximum shared memory block name length in chars */ > #define ODP_SHM_NAME_LEN 32 > > > @@ -33,6 +33,9 @@ extern "C" { > * @param align Block alignment in bytes > * > * @return Pointer to the reserved block, or NULL > + * > + * @note The same block name cannot be reused. > + * @note There is no way to unreserve a named block I think there will be a odp_shm_release call. So I'd not put that last note there...otherwise half of the current API should be noted about missing features. The problem I face is that this is the API as it stands, and we don't have any roadmap that says the symmetry will be added by 1.0, we need one. It comes into focus right now that the unit tests are running into it.The test cases either have to prove an API that does not exist or up date the docs to match reality and test against that. I feel the best approach rather than add todo allover is to actually document reality, prove it with the unit tests, and then update the code/docs/unit tests as we make progress. -Petri > */ > void *odp_shm_reserve(const char *name, uint64_t size, uint64_t align); > > -- > 1.9.1 > > > _______________________________________________ > lng-odp mailing list > [email protected]<mailto:[email protected]> > http://lists.linaro.org/mailman/listinfo/lng-odp -- Mike Holmes Linaro Technical Manager / Lead LNG - ODP _______________________________________________ lng-odp mailing list [email protected]<mailto:[email protected]> http://lists.linaro.org/mailman/listinfo/lng-odp
_______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
