# Are there any convenient reference documents for developing?



## jronald (May 6, 2015)

I think it is critically important, because it is boring to remember the functions, and it is a pleasure if there is a convenient way to reference it. BTW, MSDN have done it well.

I think the quality of FreeBSD documents is good enough for itself, and convenient/natural for the writers , however they are articles, so not convenient for the developer to find what he/she wants in the not explicitly structured articles.

If there is a explicit structure, the documents will be in a good position for referencability improving and quality improving, agree?

My first question is that: Is there any convenient reference documents for developing now?


----------



## obsigna (May 6, 2015)

I use the GNU C Library reference for developing tools for FreeBSD in C. If you want to develop in another language and/or GUI stuff, then please specify.


----------



## jronald (May 6, 2015)

obsigna said:


> I use the GNU C Library reference for developing tools for FreeBSD in C. If you want to develop in another language and/or GUI stuff, then please specify.


Well, it is not well structured, for example:


```
Function: void * obstack_base (struct obstack *obstack-ptr)

Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | See POSIX Safety Concepts.

This function returns the tentative address of the beginning of the currently growing object in obstack-ptr. If you finish the object immediately, it will have that address. If you make it larger first, it may outgrow the current chunk—then its address will change!

If no object is growing, this value says where the next object you allocate will start (once again assuming it fits in the current chunk).
```

Not good enough for daily use, it is an article, so it includes unnecessary words, and not a little.
Tried to rewrite it:


```
Function: void * obstack_base (struct obstack *obstack-ptr)

Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | See POSIX Safety Concepts.

return:
   the tentative address of the beginning of the currently growing object in obstack-ptr.
   If you finish the object immediately, it will have that address.
   If you make it larger first, it may  outgrow the current chunk—then its address will change!
   If no object is growing, this value says where the next object you allocate will start (once
   again assuming it fits in the current chunk).

obstack-ptr:
   (description of obstack-ptr should be explicit to save referencers' time)
```


----------



## SirDice (May 6, 2015)

There are a lot of man pages, even for libc syscalls. But those aren't really a complete reference, they obviously only deal with a specific syscall (or family of calls). They do contain a wealth of information though. I'm sure you've already found the Developer's handbook but to be honest it looks a little thin and high level, not really reference material.


----------



## jronald (May 7, 2015)

SirDice said:


> There are a lot of man pages, even for libc syscalls. But those aren't really a complete reference, they obviously only deal with a specific syscall (or family of calls). They do contain a wealth of information though. I'm sure you've already found the Developer's handbook but to be honest it looks a little thin and high level, not really reference material.



The problem is that the documents are articles,  in which sentences are high coherent artificially, and an article is harder to improve than structured ones, which are more discrete, because improve part of it may break the continuity between the sentences, so it needs more art to modify/improve the article, however what needs is technical, not art here, for time saving.


----------

