Dan Williams <dan.j.williams(a)intel.com> writes:
On Wed, Feb 26, 2020 at 1:52 PM Jeff Moyer <jmoyer(a)redhat.com>
> Dan Williams <dan.j.williams(a)intel.com> writes:
> >> Missing doctext. Specifically, there should be a big, fat warning
> >> against changing the region alignment.
> > I don't mind adding one, but is this the right place to document an
> > API warning? If the audience is future ndctl developers that should be
> > warned to keep the status quo of not plumbing this capability into
> > "create-namespace" that's one message. If it's to stop other
> > application developers, they'll likely never see this source file.
> I meant to target users of the library (not ndctl developers). I
> thought that was the reason for the doctext on exported interfaces. No?
> I admit, I don't know how users of libndctl figure *anything* out about
> how to use it. :)
Right, that's why I was confused about what you were asking. We
haven't yet formalized a library documentation system, which is bad.
I'll add kernel-doc for this function, and add an item to the backlog
to figure out how to build library-documentation from those
annotations. The developer's guide to date has unfortunately been "go
review how ndctl uses it".
OK, thanks a lot!