[FFmpeg-devel] [PATCH 1/2] doc/Makefile: scan all files, including .c files, for Doxygen

[Stefano Sabatini]

On date Saturday 2013-11-02 21:12:45 +0100, Michael Niedermayer encoded:
> On Sat, Nov 02, 2013 at 12:54:31PM -0700, Timothy Gu wrote:
[...]
> > 1. The 2 types of Doxygen should be clearly documented on
> > website/documentation and also how to generate them.
> 
> yes
> 
> 
> > 
> > 2a. The Doxygen on the website should be generated by `make apidoc`, not
> > the current form (with the other patch in the patch set which fixes style
> > of course).
> > 2b. An alternative solution to 2a is to change the section name on the
> > website from "API doc" to "Doxygen doc for FFmpeg developers", but this
> > method should not be used as not many FFmpeg devs use Doxygen AFAIK.
> 
> 2c. build both variants on the server (though i dont volunteer
> setting that up)
> 
> 
> > 
> > 3. Optionally add another build rule in Makefile.
> 
> this could make sense, anyone else has oppinons about that or what
> exact command the 2nd rule should have ?

I'd say that our currently generated Doxygen is confused at best.
What's the supposed use of modules, what's the supposed use of
"namespace"?

Also, but unrelated, library definitions are a bit funny, for example
I didn't know libavfilter was a "graph-based frame editing library",
which is a pretty wild interpretation of what I though libavfilter was
all about.

We should probably get rid of namespace altogethers, and try to give a
reasonable definition of "module". For a C project each "module"
comprises a file, but for example here:
http://ffmpeg.org/doxygen/trunk/group__lavu.html

I can only see the version.h file.

As I see it, "modules" as currently defined are an arbitrary
schizofrenic half-baked attempt to provide some form of
classification/grouping.

For example in case of libavutil:

  	Crypto and Hashing
  	Maths
 	String Manipulation
 	Memory Management
  	Data Structures
  	Audio related
  	Error Codes
  	Logging Facility
  	Other
 
Audio related comprises several C files and seems too much
coarse-grained, same for Data Structures, not to talk about "Other".

Things are much worse in the case of libavcodec:
 	Decoding
  	Encoding
 	Codecs
 	Internal
 	Core functions/structures.
 	Basic definitions, functions for querying libavcodec capabilities, allocating core structures, etc.
 	Utility functions
 	Miscellaneous utility functions related to both encoding and decoding (or neither). 

In this case it is not even clear what a module is meant to be (is a
codec a module? Are we talking about internal components or interface
functionality provided by a subset of functions/structures? Because
this "classification" is mixing the two). "Internal" is a again too
much coarse-grained to be considered a module at the same level as the
others, and overlaps with the other defined "modules".

In short I don't think "modules" defined at the doxygen level are
useful at all, and I think we should stick to the C-language idea of
module which equates a "module" to an header, which is also what's
used in practice by the API user when she decides what headers to
include.

...

BTW we should be probably get rid of all the imported trash from other
projects and from the scripts, such as:
http://ffmpeg.org/doxygen/trunk/namespacenormalize.html

...

Much to the point, about the API to generate. I don't think developers
will make any use of internal API, so we should focus instead on
giving a sane display of the public API.

Indeed per-policy we don't require developers to document internal API
(and for a reason), but they are de-facto required to describe the
public API (and again for a reason).

So we should probably have a make doxygen command to generate sane
public API documentation (what we currently do with doxygen
doc/Doxygen) but I won't invest time exposing internal documentation,
thus adding to the general confusion.
-- 
FFmpeg = Friendly Frenzy Merciful Pure Easy Guru