perf symbols: Add documentation to 'struct symbol'

Refactor some existing comments and then infer the rest.

Signed-off-by: Ian Rogers <irogers@google.com>
Acked-by: Namhyung Kim <namhyung@kernel.org>
Cc: Alexander Shishkin <alexander.shishkin@linux.intel.com>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: James Clark <james.clark@arm.com>
Cc: Jiri Olsa <jolsa@redhat.com>
Cc: Kajol Jain <kjain@linux.ibm.com>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Martin Liška <mliska@suse.cz>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Stephane Eranian <eranian@google.com>
Link: https://lore.kernel.org/r/20211112035124.94327-1-irogers@google.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>

diff --git a/tools/perf/util/symbol.h b/tools/perf/util/symbol.h
index 1661966..3586fa5 100644 (file)
--- a/tools/perf/util/symbol.h
+++ b/tools/perf/util/symbol.h
@@ -40,22 +40,33 @@ Elf_Scn *elf_section_by_name(Elf *elf, GElf_Ehdr *ep,
                             GElf_Shdr *shp, const char *name, size_t *idx);
 #endif
 
-/** struct symbol - symtab entry
- *
- * @ignore - resolvable but tools ignore it (e.g. idle routines)
+/**
+ * A symtab entry. When allocated this may be preceded by an annotation (see
+ * symbol__annotation), a browser_index (see symbol__browser_index) and rb_node
+ * to sort by name (see struct symbol_name_rb_node).
  */
 struct symbol {
        struct rb_node  rb_node;
+       /** Range of symbol [start, end). */
        u64             start;
        u64             end;
+       /** Length of the string name. */
        u16             namelen;
+       /** ELF symbol type as defined for st_info. E.g STT_OBJECT or STT_FUNC. */
        u8              type:4;
+       /** ELF binding type as defined for st_info. E.g. STB_WEAK or STB_GLOBAL. */
        u8              binding:4;
+       /** Set true for kernel symbols of idle routines. */
        u8              idle:1;
+       /** Resolvable but tools ignore it (e.g. idle routines). */
        u8              ignore:1;
+       /** Symbol for an inlined function. */
        u8              inlined:1;
+       /** Architecture specific. Unused except on PPC where it holds st_other. */
        u8              arch_sym;
+       /** Has symbol__annotate2 been performed. */
        bool            annotate2;
+       /** The name of length namelen associated with the symbol. */
        char            name[];
 };